mirror of
https://github.com/LonamiWebs/Telethon.git
synced 2025-03-13 16:05:49 +03:00
Compare commits
No commits in common. "v1" and "v1.4.3" have entirely different histories.
|
|
@ -1,8 +0,0 @@
|
|||
[run]
|
||||
branch = true
|
||||
parallel = true
|
||||
source =
|
||||
telethon
|
||||
|
||||
[report]
|
||||
precision = 2
|
||||
15
.github/ISSUE_TEMPLATE.md
vendored
Normal file
15
.github/ISSUE_TEMPLATE.md
vendored
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
DON'T ASK QUESTIONS HERE.
|
||||
|
||||
This place is for issues with the library, so please make sure that:
|
||||
1. The error is in the library's code, and not in your own.
|
||||
2. You have already searched for your error on existing issues.
|
||||
3. You are testing with upstream code (pip install -U https://github.com/LonamiWebs/Telethon/archive/master.zip).
|
||||
|
||||
If you have a question, ask in the official Telegram group https://t.me/TelethonChat or https://stackoverflow.com. Enhancement ideas are currently welcome, too.
|
||||
|
||||
If you paste code, please put it between three backticks (`):
|
||||
```python
|
||||
code here
|
||||
```
|
||||
|
||||
Once you have read and understood this, delete all this text and detail whatever issue you are posting.
|
||||
96
.github/ISSUE_TEMPLATE/bug-report.yml
vendored
96
.github/ISSUE_TEMPLATE/bug-report.yml
vendored
|
|
@ -1,96 +0,0 @@
|
|||
name: Bug Report
|
||||
description: Create a report about a bug inside the library.
|
||||
body:
|
||||
|
||||
- type: textarea
|
||||
id: reproducing-example
|
||||
attributes:
|
||||
label: Code that causes the issue
|
||||
description: Provide a code example that reproduces the problem. Try to keep it short without other dependencies.
|
||||
placeholder: |
|
||||
```python
|
||||
from telethon.sync import TelegramClient
|
||||
...
|
||||
|
||||
```
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: expected-behavior
|
||||
attributes:
|
||||
label: Expected behavior
|
||||
description: Explain what you should expect to happen. Include reproduction steps.
|
||||
placeholder: |
|
||||
"I was doing... I was expecting the following to happen..."
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: actual-behavior
|
||||
attributes:
|
||||
label: Actual behavior
|
||||
description: Explain what actually happens.
|
||||
placeholder: |
|
||||
"This happened instead..."
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: traceback
|
||||
attributes:
|
||||
label: Traceback
|
||||
description: |
|
||||
The traceback, if the problem is a crash.
|
||||
placeholder: |
|
||||
```
|
||||
Traceback (most recent call last):
|
||||
File "code.py", line 1, in <code>
|
||||
|
||||
```
|
||||
|
||||
- type: input
|
||||
id: telethon-version
|
||||
attributes:
|
||||
label: Telethon version
|
||||
description: The output of `python -c "import telethon; print(telethon.__version__)"`.
|
||||
placeholder: "1.x"
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: input
|
||||
id: python-version
|
||||
attributes:
|
||||
label: Python version
|
||||
description: The output of `python --version`.
|
||||
placeholder: "3.x"
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: input
|
||||
id: os
|
||||
attributes:
|
||||
label: Operating system (including distribution name and version)
|
||||
placeholder: Windows 11, macOS 13.4, Ubuntu 23.04...
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: other-details
|
||||
attributes:
|
||||
label: Other details
|
||||
placeholder: |
|
||||
Additional details and attachments. Is it a server? Network condition?
|
||||
|
||||
- type: checkboxes
|
||||
id: checklist
|
||||
attributes:
|
||||
label: Checklist
|
||||
description: Read this carefully, we will close and ignore your issue if you skimmed through this.
|
||||
options:
|
||||
- label: The error is in the library's code, and not in my own.
|
||||
required: true
|
||||
- label: I have searched for this issue before posting it and there isn't an open duplicate.
|
||||
required: true
|
||||
- label: I ran `pip install -U https://github.com/LonamiWebs/Telethon/archive/v1.zip` and triggered the bug in the latest version.
|
||||
required: true
|
||||
8
.github/ISSUE_TEMPLATE/config.yml
vendored
8
.github/ISSUE_TEMPLATE/config.yml
vendored
|
|
@ -1,8 +0,0 @@
|
|||
blank_issues_enabled: false
|
||||
contact_links:
|
||||
- name: Ask questions in StackOverflow
|
||||
url: https://stackoverflow.com/questions/ask?tags=telethon
|
||||
about: Questions are not bugs. Please ask them in StackOverflow instead. Questions in the bug tracker will be closed
|
||||
- name: Find about updates and our Telegram groups
|
||||
url: https://t.me/s/TelethonUpdates
|
||||
about: Be notified of updates, chat with other people about the library or ask questions in these groups
|
||||
22
.github/ISSUE_TEMPLATE/documentation-issue.yml
vendored
22
.github/ISSUE_TEMPLATE/documentation-issue.yml
vendored
|
|
@ -1,22 +0,0 @@
|
|||
name: Documentation Issue
|
||||
description: Report a problem with the documentation.
|
||||
labels: [documentation]
|
||||
body:
|
||||
|
||||
- type: textarea
|
||||
id: description
|
||||
attributes:
|
||||
label: Description
|
||||
description: Describe the problem in detail.
|
||||
placeholder: This part is unclear...
|
||||
|
||||
- type: checkboxes
|
||||
id: checklist
|
||||
attributes:
|
||||
label: Checklist
|
||||
description: Read this carefully, we will close and ignore your issue if you skimmed through this.
|
||||
options:
|
||||
- label: This is a documentation problem, not a question or a bug report.
|
||||
required: true
|
||||
- label: I have searched for this issue before posting it and there isn't a duplicate.
|
||||
required: true
|
||||
22
.github/ISSUE_TEMPLATE/feature-request.yml
vendored
22
.github/ISSUE_TEMPLATE/feature-request.yml
vendored
|
|
@ -1,22 +0,0 @@
|
|||
name: Feature Request
|
||||
description: Suggest ideas, changes or other enhancements for the library.
|
||||
labels: [enhancement]
|
||||
body:
|
||||
|
||||
- type: textarea
|
||||
id: feature-description
|
||||
attributes:
|
||||
label: Describe your suggested feature
|
||||
description: Please describe your idea. Would you like another friendly method? Renaming them to something more appropriate? Changing the way something works?
|
||||
placeholder: "It should work like this..."
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: checkboxes
|
||||
id: checklist
|
||||
attributes:
|
||||
label: Checklist
|
||||
description: Read this carefully, we will close and ignore your issue if you skimmed through this.
|
||||
options:
|
||||
- label: I have searched for this issue before posting it and there isn't a duplicate.
|
||||
required: true
|
||||
5
.github/pull_request_template.md
vendored
5
.github/pull_request_template.md
vendored
|
|
@ -1,5 +0,0 @@
|
|||
<!--
|
||||
Thanks for the PR! Please keep in mind that v1 is *feature frozen*.
|
||||
New features very likely won't be merged, although fixes can be sent.
|
||||
All new development should happen in v2. Thanks!
|
||||
-->
|
||||
28
.github/workflows.disabled/python.yml
vendored
28
.github/workflows.disabled/python.yml
vendored
|
|
@ -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
|
||||
115
.gitignore
vendored
115
.gitignore
vendored
|
|
@ -1,23 +1,108 @@
|
|||
# Docs
|
||||
_build/
|
||||
docs/
|
||||
|
||||
# Generated code
|
||||
/telethon/tl/functions/
|
||||
/telethon/tl/types/
|
||||
/telethon/tl/alltlobjects.py
|
||||
/telethon/errors/rpcerrorlist.py
|
||||
telethon/tl/functions/
|
||||
telethon/tl/types/
|
||||
telethon/tl/patched/
|
||||
telethon/tl/alltlobjects.py
|
||||
telethon/errors/rpcerrorlist.py
|
||||
|
||||
# User session
|
||||
*.session
|
||||
/usermedia/
|
||||
usermedia/
|
||||
|
||||
# Builds and testing
|
||||
# Quick tests should live in this file
|
||||
example.py
|
||||
|
||||
# Byte-compiled / optimized / DLL files
|
||||
__pycache__/
|
||||
/dist/
|
||||
/build/
|
||||
/*.egg-info/
|
||||
/readthedocs/_build/
|
||||
/.tox/
|
||||
*.py[cod]
|
||||
*$py.class
|
||||
|
||||
# API reference docs
|
||||
/docs/
|
||||
# C extensions
|
||||
*.so
|
||||
|
||||
# File used to manually test new changes, contains sensitive data
|
||||
/example.py
|
||||
# Distribution / packaging
|
||||
.Python
|
||||
env/
|
||||
build/
|
||||
develop-eggs/
|
||||
dist/
|
||||
downloads/
|
||||
eggs/
|
||||
.eggs/
|
||||
lib/
|
||||
lib64/
|
||||
parts/
|
||||
sdist/
|
||||
var/
|
||||
*.egg-info/
|
||||
.installed.cfg
|
||||
*.egg
|
||||
|
||||
# PyInstaller
|
||||
# Usually these files are written by a python script from a template
|
||||
# before PyInstaller builds the exe, so as to inject date/other infos into it.
|
||||
*.manifest
|
||||
*.spec
|
||||
|
||||
# Installer logs
|
||||
pip-log.txt
|
||||
pip-delete-this-directory.txt
|
||||
|
||||
# Unit test / coverage reports
|
||||
htmlcov/
|
||||
.tox/
|
||||
.coverage
|
||||
.coverage.*
|
||||
.cache
|
||||
nosetests.xml
|
||||
coverage.xml
|
||||
*,cover
|
||||
.hypothesis/
|
||||
|
||||
# Translations
|
||||
*.mo
|
||||
*.pot
|
||||
|
||||
# Django stuff:
|
||||
*.log
|
||||
local_settings.py
|
||||
|
||||
# Flask stuff:
|
||||
instance/
|
||||
.webassets-cache
|
||||
|
||||
# Scrapy stuff:
|
||||
.scrapy
|
||||
|
||||
# Sphinx documentation
|
||||
docs/_build/
|
||||
|
||||
# PyBuilder
|
||||
target/
|
||||
|
||||
# IPython Notebook
|
||||
.ipynb_checkpoints
|
||||
|
||||
# pyenv
|
||||
.python-version
|
||||
|
||||
# celery beat schedule file
|
||||
celerybeat-schedule
|
||||
|
||||
# dotenv
|
||||
.env
|
||||
|
||||
# virtualenv
|
||||
.venv/
|
||||
venv/
|
||||
ENV/
|
||||
|
||||
# Spyder project settings
|
||||
.spyderproject
|
||||
|
||||
# Rope project settings
|
||||
.ropeproject
|
||||
|
|
|
|||
|
|
@ -1,18 +0,0 @@
|
|||
# https://docs.readthedocs.io/en/stable/config-file/v2.html
|
||||
version: 2
|
||||
|
||||
build:
|
||||
os: ubuntu-22.04
|
||||
tools:
|
||||
python: "3.11"
|
||||
|
||||
sphinx:
|
||||
configuration: readthedocs/conf.py
|
||||
|
||||
formats:
|
||||
- pdf
|
||||
- epub
|
||||
|
||||
python:
|
||||
install:
|
||||
- requirements: readthedocs/requirements.txt
|
||||
2
LICENSE
2
LICENSE
|
|
@ -1,6 +1,6 @@
|
|||
MIT License
|
||||
|
||||
Copyright (c) 2016-Present LonamiWebs
|
||||
Copyright (c) 2016 LonamiWebs
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
|
|
|
|||
4
MANIFEST.in
Normal file
4
MANIFEST.in
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
include LICENSE
|
||||
include README.rst
|
||||
|
||||
recursive-include telethon *
|
||||
11
README.rst
11
README.rst
|
|
@ -5,15 +5,12 @@ Telethon
|
|||
⭐️ Thanks **everyone** who has starred the project, it means a lot!
|
||||
|
||||
|logo| **Telethon** is an asyncio_ **Python 3**
|
||||
MTProto_ library to interact with Telegram_'s API
|
||||
as a user or through a bot account (bot API alternative).
|
||||
MTProto_ library to interact with Telegram_'s API.
|
||||
|
||||
.. important::
|
||||
|
||||
If you have code using Telethon before its 1.0 version, you must
|
||||
read `Compatibility and Convenience`_ to learn how to migrate.
|
||||
As with any third-party library for Telegram, be careful not to
|
||||
break `Telegram's ToS`_ or `Telegram can ban the account`_.
|
||||
|
||||
What is this?
|
||||
-------------
|
||||
|
|
@ -77,10 +74,8 @@ 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/stable/misc/compatibility-and-convenience.html
|
||||
.. _Telegram's ToS: https://core.telegram.org/api/terms
|
||||
.. _Telegram can ban the account: https://docs.telethon.dev/en/stable/quick-references/faq.html#my-account-was-deleted-limited-when-using-the-library
|
||||
.. _Read The Docs: https://docs.telethon.dev
|
||||
.. _Compatibility and Convenience: https://telethon.readthedocs.io/en/latest/extra/basic/compatibility-and-convenience.html
|
||||
.. _Read The Docs: https://telethon.readthedocs.io
|
||||
|
||||
.. |logo| image:: logo.svg
|
||||
:width: 24pt
|
||||
|
|
|
|||
|
|
@ -1,3 +0,0 @@
|
|||
pytest
|
||||
pytest-cov
|
||||
pytest-asyncio
|
||||
|
|
@ -1,5 +1,3 @@
|
|||
cryptg
|
||||
pysocks
|
||||
python-socks[asyncio]
|
||||
hachoir
|
||||
pillow
|
||||
hachoir3
|
||||
|
|
|
|||
|
|
@ -1,36 +0,0 @@
|
|||
# https://snarky.ca/what-the-heck-is-pyproject-toml/
|
||||
[build-system]
|
||||
requires = ["setuptools", "wheel"]
|
||||
build-backend = "setuptools.build_meta"
|
||||
|
||||
# Need to use legacy format for the time being
|
||||
# https://tox.readthedocs.io/en/3.20.0/example/basic.html#pyproject-toml-tox-legacy-ini
|
||||
[tool.tox]
|
||||
legacy_tox_ini = """
|
||||
[tox]
|
||||
envlist = py35,py36,py37,py38
|
||||
|
||||
# run with tox -e py
|
||||
[testenv]
|
||||
deps =
|
||||
-rrequirements.txt
|
||||
-roptional-requirements.txt
|
||||
-rdev-requirements.txt
|
||||
commands =
|
||||
# NOTE: you can run any command line tool here - not just tests
|
||||
pytest {posargs}
|
||||
|
||||
# run with tox -e flake
|
||||
[testenv:flake]
|
||||
deps =
|
||||
-rrequirements.txt
|
||||
-roptional-requirements.txt
|
||||
-rdev-requirements.txt
|
||||
flake8
|
||||
commands =
|
||||
# stop the build if there are Python syntax errors or undefined names
|
||||
flake8 telethon/ telethon_generator/ tests/ --count --select=E9,F63,F7,F82 --show-source --statistics
|
||||
# exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
|
||||
flake8 telethon/ telethon_generator/ tests/ --count --exit-zero --exclude telethon/tl/,telethon/errors/rpcerrorlist.py --max-complexity=10 --max-line-length=127 --statistics
|
||||
|
||||
"""
|
||||
|
|
@ -1,96 +0,0 @@
|
|||
.. _installation:
|
||||
|
||||
============
|
||||
Installation
|
||||
============
|
||||
|
||||
Telethon is a Python library, which means you need to download and install
|
||||
Python from https://www.python.org/downloads/ if you haven't already. Once
|
||||
you have Python installed, `upgrade pip`__ and run:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
python3 -m pip install --upgrade pip
|
||||
python3 -m pip install --upgrade telethon
|
||||
|
||||
…to install or upgrade the library to the latest version.
|
||||
|
||||
.. __: https://pythonspeed.com/articles/upgrade-pip/
|
||||
|
||||
Installing Development Versions
|
||||
===============================
|
||||
|
||||
If you want the *latest* unreleased changes,
|
||||
you can run the following command instead:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
python3 -m pip install --upgrade https://github.com/LonamiWebs/Telethon/archive/v1.zip
|
||||
|
||||
.. note::
|
||||
|
||||
The development version may have bugs and is not recommended for production
|
||||
use. However, when you are `reporting a library bug`__, you should try if the
|
||||
bug still occurs in this version.
|
||||
|
||||
.. __: https://github.com/LonamiWebs/Telethon/issues/
|
||||
|
||||
|
||||
Verification
|
||||
============
|
||||
|
||||
To verify that the library is installed correctly, run the following command:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
python3 -c "import telethon; print(telethon.__version__)"
|
||||
|
||||
The version number of the library should show in the output.
|
||||
|
||||
|
||||
Optional Dependencies
|
||||
=====================
|
||||
|
||||
If cryptg_ is installed, **the library will work a lot faster**, since
|
||||
encryption and decryption will be made in C instead of Python. If your
|
||||
code deals with a lot of updates or you are downloading/uploading a lot
|
||||
of files, you will notice a considerable speed-up (from a hundred kilobytes
|
||||
per second to several megabytes per second, if your connection allows it).
|
||||
If it's not installed, pyaes_ will be used (which is pure Python, so it's
|
||||
much slower).
|
||||
|
||||
If pillow_ is installed, large images will be automatically resized when
|
||||
sending photos to prevent Telegram from failing with "invalid image".
|
||||
Official clients also do this.
|
||||
|
||||
If aiohttp_ is installed, the library will be able to download
|
||||
:tl:`WebDocument` media files (otherwise you will get an error).
|
||||
|
||||
If hachoir_ is installed, it will be used to extract metadata from files
|
||||
when sending documents. Telegram uses this information to show the song's
|
||||
performer, artist, title, duration, and for videos too (including size).
|
||||
Otherwise, they will default to empty values, and you can set the attributes
|
||||
manually.
|
||||
|
||||
.. note::
|
||||
|
||||
Some of the modules may require additional dependencies before being
|
||||
installed through ``pip``. If you have an ``apt``-based system, consider
|
||||
installing the most commonly missing dependencies (with the right ``pip``):
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
apt update
|
||||
apt install clang lib{jpeg-turbo,webp}-dev python{,-dev} zlib-dev
|
||||
pip install -U --user setuptools
|
||||
pip install -U --user telethon cryptg pillow
|
||||
|
||||
Thanks to `@bb010g`_ for writing down this nice list.
|
||||
|
||||
|
||||
.. _cryptg: https://github.com/cher-nov/cryptg
|
||||
.. _pyaes: https://github.com/ricmoo/pyaes
|
||||
.. _pillow: https://python-pillow.org
|
||||
.. _aiohttp: https://docs.aiohttp.org
|
||||
.. _hachoir: https://hachoir.readthedocs.io
|
||||
.. _@bb010g: https://static.bb010g.com
|
||||
|
|
@ -1,46 +0,0 @@
|
|||
==========
|
||||
Next Steps
|
||||
==========
|
||||
|
||||
These basic first steps should have gotten you started with the library.
|
||||
|
||||
By now, you should know how to call friendly methods and how to work with
|
||||
the returned objects, how things work inside event handlers, etc.
|
||||
|
||||
Next, we will see a quick reference summary of *all* the methods and
|
||||
properties that you will need when using the library. If you follow
|
||||
the links there, you will expand the documentation for the method
|
||||
and property, with more examples on how to use them.
|
||||
|
||||
Therefore, **you can find an example on every method** of the client
|
||||
to learn how to use it, as well as a description of all the arguments.
|
||||
|
||||
After that, we will go in-depth with some other important concepts
|
||||
that are worth learning and understanding.
|
||||
|
||||
From now on, you can keep pressing the "Next" button if you want,
|
||||
or use the menu on the left, since some pages are quite lengthy.
|
||||
|
||||
A note on developing applications
|
||||
=================================
|
||||
|
||||
If you're using the library to make an actual application (and not just
|
||||
automate things), you should make sure to `comply with the ToS`__:
|
||||
|
||||
[…] when logging in as an existing user, apps are supposed to call
|
||||
[:tl:`GetTermsOfServiceUpdate`] to check for any updates to the Terms of
|
||||
Service; this call should be repeated after ``expires`` seconds have
|
||||
elapsed. If an update to the Terms Of Service is available, clients are
|
||||
supposed to show a consent popup; if accepted, clients should call
|
||||
[:tl:`AcceptTermsOfService`], providing the ``termsOfService id`` JSON
|
||||
object; in case of denial, clients are to delete the account using
|
||||
[:tl:`DeleteAccount`], providing Decline ToS update as deletion reason.
|
||||
|
||||
.. __: https://core.telegram.org/api/config#terms-of-service
|
||||
|
||||
However, if you use the library to automate or enhance your Telegram
|
||||
experience, it's very likely that you are using other applications doing this
|
||||
check for you (so you wouldn't run the risk of violating the ToS).
|
||||
|
||||
The library itself will not automatically perform this check or accept the ToS
|
||||
because it should require user action (the only exception is during sign-up).
|
||||
|
|
@ -1,111 +0,0 @@
|
|||
===========
|
||||
Quick-Start
|
||||
===========
|
||||
|
||||
Let's see a longer example to learn some of the methods that the library
|
||||
has to offer. These are known as "friendly methods", and you should always
|
||||
use these if possible.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
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():
|
||||
# Getting information about yourself
|
||||
me = await client.get_me()
|
||||
|
||||
# "me" is a user object. You can pretty-print
|
||||
# any Telegram object with the "stringify" method:
|
||||
print(me.stringify())
|
||||
|
||||
# When you print something, you see a representation of it.
|
||||
# You can access all attributes of Telegram objects with
|
||||
# the dot operator. For example, to get the username:
|
||||
username = me.username
|
||||
print(username)
|
||||
print(me.phone)
|
||||
|
||||
# You can print all the dialogs/conversations that you are part of:
|
||||
async for dialog in client.iter_dialogs():
|
||||
print(dialog.name, 'has ID', dialog.id)
|
||||
|
||||
# You can send messages to yourself...
|
||||
await client.send_message('me', 'Hello, myself!')
|
||||
# ...to some chat ID
|
||||
await client.send_message(-100123456, 'Hello, group!')
|
||||
# ...to your contacts
|
||||
await client.send_message('+34600123123', 'Hello, friend!')
|
||||
# ...or even to any username
|
||||
await client.send_message('username', 'Testing Telethon!')
|
||||
|
||||
# You can, of course, use markdown in your messages:
|
||||
message = await client.send_message(
|
||||
'me',
|
||||
'This message has **bold**, `code`, __italics__ and '
|
||||
'a [nice website](https://example.com)!',
|
||||
link_preview=False
|
||||
)
|
||||
|
||||
# Sending a message returns the sent message object, which you can use
|
||||
print(message.raw_text)
|
||||
|
||||
# You can reply to messages directly if you have a message object
|
||||
await message.reply('Cool!')
|
||||
|
||||
# Or send files, songs, documents, albums...
|
||||
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'):
|
||||
print(message.id, message.text)
|
||||
|
||||
# You can download media from messages, too!
|
||||
# The method will return the path where the file was saved.
|
||||
if message.photo:
|
||||
path = await message.download_media()
|
||||
print('File saved to', path) # printed after download is done
|
||||
|
||||
with client:
|
||||
client.loop.run_until_complete(main())
|
||||
|
||||
|
||||
Here, we show how to sign in, get information about yourself, send
|
||||
messages, files, getting chats, printing messages, and downloading
|
||||
files.
|
||||
|
||||
You should make sure that you understand what the code shown here
|
||||
does, take note on how methods are called and used and so on before
|
||||
proceeding. We will see all the available methods later on.
|
||||
|
||||
.. important::
|
||||
|
||||
Note that Telethon is an asynchronous library, and as such, you should
|
||||
get used to it and learn a bit of basic `asyncio`. This will help a lot.
|
||||
As a quick start, this means you generally want to write all your code
|
||||
inside some ``async def`` like so:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client = ...
|
||||
|
||||
async def do_something(me):
|
||||
...
|
||||
|
||||
async def main():
|
||||
# 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.
|
||||
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).
|
||||
|
|
@ -1,229 +0,0 @@
|
|||
.. _signing-in:
|
||||
|
||||
==========
|
||||
Signing In
|
||||
==========
|
||||
|
||||
Before working with Telegram's API, you need to get your own API ID and hash:
|
||||
|
||||
1. `Login to your Telegram account <https://my.telegram.org/>`_ with the
|
||||
phone number of the developer account to use.
|
||||
|
||||
2. Click under API Development tools.
|
||||
|
||||
3. A *Create new application* window will appear. Fill in your application
|
||||
details. There is no need to enter any *URL*, and only the first two
|
||||
fields (*App title* and *Short name*) can currently be changed later.
|
||||
|
||||
4. Click on *Create application* at the end. Remember that your
|
||||
**API hash is secret** and Telegram won't let you revoke it.
|
||||
Don't post it anywhere!
|
||||
|
||||
.. note::
|
||||
|
||||
This API ID and hash is the one used by *your application*, not your
|
||||
phone number. You can use this API ID and hash with *any* phone number
|
||||
or even for bot accounts.
|
||||
|
||||
|
||||
Editing the Code
|
||||
================
|
||||
|
||||
This is a little introduction for those new to Python programming in general.
|
||||
|
||||
We will write our code inside ``hello.py``, so you can use any text
|
||||
editor that you like. To run the code, use ``python3 hello.py`` from
|
||||
the terminal.
|
||||
|
||||
.. important::
|
||||
|
||||
Don't call your script ``telethon.py``! Python will try to import
|
||||
the client from there and it will fail with an error such as
|
||||
"ImportError: cannot import name 'TelegramClient' ...".
|
||||
|
||||
|
||||
Signing In
|
||||
==========
|
||||
|
||||
We can finally write some code to log into our account!
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import TelegramClient
|
||||
|
||||
# Use your own values from my.telegram.org
|
||||
api_id = 12345
|
||||
api_hash = '0123456789abcdef0123456789abcdef'
|
||||
|
||||
# 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!'))
|
||||
|
||||
|
||||
In the first line, we import the class name so we can create an instance
|
||||
of the client. Then, we define variables to store our API ID and hash
|
||||
conveniently.
|
||||
|
||||
At last, we create a new `TelegramClient <telethon.client.telegramclient.TelegramClient>`
|
||||
instance and call it ``client``. We can now use the client variable
|
||||
for anything that we want, such as sending a message to ourselves.
|
||||
|
||||
.. note::
|
||||
|
||||
Since Telethon is an asynchronous library, you need to ``await``
|
||||
coroutine functions to have them run (or otherwise, run the loop
|
||||
until they are complete). In this tiny example, we don't bother
|
||||
making an ``async def main()``.
|
||||
|
||||
See :ref:`mastering-asyncio` to find out more.
|
||||
|
||||
|
||||
Using a ``with`` block is the preferred way to use the library. It will
|
||||
automatically `start() <telethon.client.auth.AuthMethods.start>` the client,
|
||||
logging or signing up if necessary.
|
||||
|
||||
If the ``.session`` file already existed, it will not login
|
||||
again, so be aware of this if you move or rename the file!
|
||||
|
||||
|
||||
Signing In as a Bot Account
|
||||
===========================
|
||||
|
||||
You can also use Telethon for your bots (normal bot accounts, not users).
|
||||
You will still need an API ID and hash, but the process is very similar:
|
||||
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.sync 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)
|
||||
|
||||
# But then we can use the client instance as usual
|
||||
with bot:
|
||||
...
|
||||
|
||||
|
||||
To get a bot account, you need to talk
|
||||
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:
|
||||
|
||||
* For Python >= 3.6 : `install python-socks[asyncio]`__
|
||||
* For Python <= 3.5 : `install PySocks`__
|
||||
|
||||
and then change
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
TelegramClient('anon', api_id, api_hash)
|
||||
|
||||
with
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
TelegramClient('anon', api_id, api_hash, proxy=("socks5", '127.0.0.1', 4444))
|
||||
|
||||
(of course, replacing the protocol, IP and port with the protocol, IP and port of the proxy).
|
||||
|
||||
The ``proxy=`` argument should be a dict (or tuple, for backwards compatibility),
|
||||
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``
|
||||
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
proxy = {
|
||||
'proxy_type': 'socks5', # (mandatory) protocol to use (see above)
|
||||
'addr': '1.1.1.1', # (mandatory) proxy IP address
|
||||
'port': 5555, # (mandatory) proxy port number
|
||||
'username': 'foo', # (optional) username if the proxy requires auth
|
||||
'password': 'bar', # (optional) password if the proxy requires auth
|
||||
'rdns': True # (optional) whether to use remote or local resolve, default remote
|
||||
}
|
||||
|
||||
For backwards compatibility with ``PySocks`` the following format
|
||||
is possible (but discouraged):
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
proxy = (socks.SOCKS5, '1.1.1.1', 5555, True, 'foo', 'bar')
|
||||
|
||||
.. __: https://github.com/romis2012/python-socks#installation
|
||||
.. __: https://github.com/Anorov/PySocks#installation
|
||||
.. __: https://github.com/Anorov/PySocks#usage-1
|
||||
|
||||
|
||||
Using MTProto Proxies
|
||||
=====================
|
||||
|
||||
MTProto Proxies are Telegram's alternative to normal proxies,
|
||||
and work a bit differently. The following protocols are available:
|
||||
|
||||
* ``ConnectionTcpMTProxyAbridged``
|
||||
* ``ConnectionTcpMTProxyIntermediate``
|
||||
* ``ConnectionTcpMTProxyRandomizedIntermediate`` (preferred)
|
||||
|
||||
For now, you need to manually specify these special connection modes
|
||||
if you want to use a MTProto Proxy. Your code would look like this:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import TelegramClient, connection
|
||||
# we need to change the connection ^^^^^^^^^^
|
||||
|
||||
client = TelegramClient(
|
||||
'anon',
|
||||
api_id,
|
||||
api_hash,
|
||||
|
||||
# Use one of the available connection modes.
|
||||
# Normally, this one works with most proxies.
|
||||
connection=connection.ConnectionTcpMTProxyRandomizedIntermediate,
|
||||
|
||||
# Then, pass the proxy details as a tuple:
|
||||
# (host name, port, proxy secret)
|
||||
#
|
||||
# If the proxy has no secret, the secret must be:
|
||||
# '00000000000000000000000000000000'
|
||||
proxy=('mtproxy.example.com', 2002, 'secret')
|
||||
)
|
||||
|
||||
In future updates, we may make it easier to use MTProto Proxies
|
||||
(such as avoiding the need to manually pass ``connection=``).
|
||||
|
||||
In short, the same code above but without comments to make it clearer:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import TelegramClient, connection
|
||||
|
||||
client = TelegramClient(
|
||||
'anon', api_id, api_hash,
|
||||
connection=connection.ConnectionTcpMTProxyRandomizedIntermediate,
|
||||
proxy=('mtproxy.example.com', 2002, 'secret')
|
||||
)
|
||||
|
|
@ -1,159 +0,0 @@
|
|||
=======
|
||||
Updates
|
||||
=======
|
||||
|
||||
Updates are an important topic in a messaging platform like Telegram.
|
||||
After all, you want to be notified when a new message arrives, when
|
||||
a member joins, when someone starts typing, etc.
|
||||
For that, you can use **events**.
|
||||
|
||||
.. important::
|
||||
|
||||
It is strongly advised to enable logging when working with events,
|
||||
since exceptions in event handlers are hidden by default. Please
|
||||
add the following snippet to the very top of your file:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import logging
|
||||
logging.basicConfig(format='[%(levelname) %(asctime)s] %(name)s: %(message)s',
|
||||
level=logging.WARNING)
|
||||
|
||||
|
||||
Getting Started
|
||||
===============
|
||||
|
||||
Let's start things with an example to automate replies:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import TelegramClient, events
|
||||
|
||||
client = TelegramClient('anon', api_id, api_hash)
|
||||
|
||||
@client.on(events.NewMessage)
|
||||
async def my_event_handler(event):
|
||||
if 'hello' in event.raw_text:
|
||||
await event.reply('hi!')
|
||||
|
||||
client.start()
|
||||
client.run_until_disconnected()
|
||||
|
||||
|
||||
This code isn't much, but there might be some things unclear.
|
||||
Let's break it down:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import TelegramClient, events
|
||||
|
||||
client = TelegramClient('anon', api_id, api_hash)
|
||||
|
||||
|
||||
This is normal creation (of course, pass session name, API ID and hash).
|
||||
Nothing we don't know already.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@client.on(events.NewMessage)
|
||||
|
||||
|
||||
This Python decorator will attach itself to the ``my_event_handler``
|
||||
definition, and basically means that *on* a `NewMessage
|
||||
<telethon.events.newmessage.NewMessage>` *event*,
|
||||
the callback function you're about to define will be called:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
async def my_event_handler(event):
|
||||
if 'hello' in event.raw_text:
|
||||
await event.reply('hi!')
|
||||
|
||||
|
||||
If a `NewMessage
|
||||
<telethon.events.newmessage.NewMessage>` event occurs,
|
||||
and ``'hello'`` is in the text of the message, we `reply()
|
||||
<telethon.tl.custom.message.Message.reply>` to the event
|
||||
with a ``'hi!'`` message.
|
||||
|
||||
.. note::
|
||||
|
||||
Event handlers **must** be ``async def``. After all,
|
||||
Telethon is an asynchronous library based on `asyncio`,
|
||||
which is a safer and often faster approach to threads.
|
||||
|
||||
You **must** ``await`` all method calls that use
|
||||
network requests, which is most of them.
|
||||
|
||||
|
||||
More Examples
|
||||
=============
|
||||
|
||||
Replying to messages with hello is fun, but, can we do more?
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@client.on(events.NewMessage(outgoing=True, pattern=r'\.save'))
|
||||
async def handler(event):
|
||||
if event.is_reply:
|
||||
replied = await event.get_reply_message()
|
||||
sender = replied.sender
|
||||
await client.download_profile_photo(sender)
|
||||
await event.respond('Saved your photo {}'.format(sender.username))
|
||||
|
||||
We could also get replies. This event filters outgoing messages
|
||||
(only those that we send will trigger the method), then we filter
|
||||
by the regex ``r'\.save'``, which will match messages starting
|
||||
with ``".save"``.
|
||||
|
||||
Inside the method, we check whether the event is replying to another message
|
||||
or not. If it is, we get the reply message and the sender of that message,
|
||||
and download their profile photo.
|
||||
|
||||
Let's delete messages which contain "heck". We don't allow swearing here.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@client.on(events.NewMessage(pattern=r'(?i).*heck'))
|
||||
async def handler(event):
|
||||
await event.delete()
|
||||
|
||||
|
||||
With the ``r'(?i).*heck'`` regex, we match case-insensitive
|
||||
"heck" anywhere in the message. Regex is very powerful and you
|
||||
can learn more at https://regexone.com/.
|
||||
|
||||
So far, we have only seen the `NewMessage
|
||||
<telethon.events.newmessage.NewMessage>`, but there are many more
|
||||
which will be covered later. This is only a small introduction to updates.
|
||||
|
||||
Entities
|
||||
========
|
||||
|
||||
When you need the user or chat where an event occurred, you **must** use
|
||||
the following methods:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
async def handler(event):
|
||||
# Good
|
||||
chat = await event.get_chat()
|
||||
sender = await event.get_sender()
|
||||
chat_id = event.chat_id
|
||||
sender_id = event.sender_id
|
||||
|
||||
# BAD. Don't do this
|
||||
chat = event.chat
|
||||
sender = event.sender
|
||||
chat_id = event.chat.id
|
||||
sender_id = event.sender.id
|
||||
|
||||
Events are like messages, but don't have all the information a message has!
|
||||
When you manually get a message, it will have all the information it needs.
|
||||
When you receive an update about a message, it **won't** have all the
|
||||
information, so you have to **use the methods**, not the properties.
|
||||
|
||||
Make sure you understand the code seen here before continuing!
|
||||
As a rule of thumb, remember that new message events behave just
|
||||
like message objects, so you can do with them everything you can
|
||||
do with a message object.
|
||||
|
|
@ -1,336 +0,0 @@
|
|||
.. _botapi:
|
||||
|
||||
=======================
|
||||
HTTP Bot API vs MTProto
|
||||
=======================
|
||||
|
||||
|
||||
Telethon is more than just another viable alternative when developing bots
|
||||
for Telegram. If you haven't decided which wrapper library for bots to use
|
||||
yet, using Telethon from the beginning may save you some headaches later.
|
||||
|
||||
.. contents::
|
||||
|
||||
|
||||
What is Bot API?
|
||||
================
|
||||
|
||||
The `Telegram Bot API`_, also known as HTTP Bot API and from now on referred
|
||||
to as simply "Bot API" is Telegram's official way for developers to control
|
||||
their own Telegram bots. Quoting their main page:
|
||||
|
||||
The Bot API is an HTTP-based interface created for developers keen on
|
||||
building bots for Telegram.
|
||||
|
||||
To learn how to create and set up a bot, please consult our
|
||||
`Introduction to Bots`_ and `Bot FAQ`_.
|
||||
|
||||
Bot API is simply an HTTP endpoint which translates your requests to it into
|
||||
MTProto calls through tdlib_, their bot backend.
|
||||
|
||||
Configuration of your bot, such as its available commands and auto-completion,
|
||||
is configured through `@BotFather <https://t.me/BotFather>`_.
|
||||
|
||||
|
||||
What is MTProto?
|
||||
================
|
||||
|
||||
MTProto_ is Telegram's own protocol to communicate with their API when you
|
||||
connect to their servers.
|
||||
|
||||
Telethon is an alternative MTProto-based backend written entirely in Python
|
||||
and much easier to setup and use.
|
||||
|
||||
Both official applications and third-party clients (like your own
|
||||
applications) logged in as either user or bots **can use MTProto** to
|
||||
communicate directly with Telegram's API (which is not the HTTP bot API).
|
||||
|
||||
When we talk about MTProto, we often mean "MTProto-based clients".
|
||||
|
||||
|
||||
Advantages of MTProto over Bot API
|
||||
==================================
|
||||
|
||||
MTProto clients (like Telethon) connect directly to Telegram's servers,
|
||||
which means there is no HTTP connection, no "polling" or "web hooks". This
|
||||
means **less overhead**, since the protocol used between you and the server
|
||||
is much more compact than HTTP requests with responses in wasteful JSON.
|
||||
|
||||
Since there is a direct connection to Telegram's servers, even if their
|
||||
Bot API endpoint is down, you can still have connection to Telegram directly.
|
||||
|
||||
Using a MTProto client, you are also not limited to the public API that
|
||||
they expose, and instead, **you have full control** of what your bot can do.
|
||||
Telethon offers you all the power with often **much easier usage** than any
|
||||
of the available Python Bot API wrappers.
|
||||
|
||||
If your application ever needs user features because bots cannot do certain
|
||||
things, you will be able to easily login as a user and even keep your bot
|
||||
without having to learn a new library.
|
||||
|
||||
If less overhead and full control didn't convince you to use Telethon yet,
|
||||
check out the wiki page `MTProto vs HTTP Bot API`_ with a more exhaustive
|
||||
and up-to-date list of differences.
|
||||
|
||||
|
||||
Migrating from Bot API to Telethon
|
||||
==================================
|
||||
|
||||
It doesn't matter if you wrote your bot with requests_ and you were
|
||||
making API requests manually, or if you used a wrapper library like
|
||||
python-telegram-bot_ or pyTelegramBotAPI_. It's never too late to
|
||||
migrate to Telethon!
|
||||
|
||||
If you were using an asynchronous library like aiohttp_ or a wrapper like
|
||||
aiogram_ or dumbot_, it will be even easier, because Telethon is also an
|
||||
asynchronous library.
|
||||
|
||||
Next, we will see some examples from the most popular libraries.
|
||||
|
||||
|
||||
Migrating from python-telegram-bot
|
||||
----------------------------------
|
||||
|
||||
Let's take their `echobot.py`_ example and shorten it a bit:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telegram.ext import Updater, CommandHandler, MessageHandler, Filters
|
||||
|
||||
def start(update, context):
|
||||
"""Send a message when the command /start is issued."""
|
||||
update.message.reply_text('Hi!')
|
||||
|
||||
def echo(update, context):
|
||||
"""Echo the user message."""
|
||||
update.message.reply_text(update.message.text)
|
||||
|
||||
def main():
|
||||
"""Start the bot."""
|
||||
updater = Updater("TOKEN")
|
||||
dp = updater.dispatcher
|
||||
dp.add_handler(CommandHandler("start", start))
|
||||
dp.add_handler(MessageHandler(Filters.text & ~Filters.command, echo))
|
||||
|
||||
updater.start_polling()
|
||||
|
||||
updater.idle()
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
|
||||
|
||||
After using Telethon:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import TelegramClient, events
|
||||
|
||||
bot = TelegramClient('bot', 11111, 'a1b2c3d4').start(bot_token='TOKEN')
|
||||
|
||||
@bot.on(events.NewMessage(pattern='/start'))
|
||||
async def start(event):
|
||||
"""Send a message when the command /start is issued."""
|
||||
await event.respond('Hi!')
|
||||
raise events.StopPropagation
|
||||
|
||||
@bot.on(events.NewMessage)
|
||||
async def echo(event):
|
||||
"""Echo the user message."""
|
||||
await event.respond(event.text)
|
||||
|
||||
def main():
|
||||
"""Start the bot."""
|
||||
bot.run_until_disconnected()
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
|
||||
Key differences:
|
||||
|
||||
* 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``.
|
||||
* The ``bot`` isn't hidden away by ``Updater`` or ``Dispatcher``.
|
||||
|
||||
|
||||
Migrating from pyTelegramBotAPI
|
||||
-------------------------------
|
||||
|
||||
Let's show another echobot from their README:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import telebot
|
||||
|
||||
bot = telebot.TeleBot("TOKEN")
|
||||
|
||||
@bot.message_handler(commands=['start'])
|
||||
def send_welcome(message):
|
||||
bot.reply_to(message, "Howdy, how are you doing?")
|
||||
|
||||
@bot.message_handler(func=lambda m: True)
|
||||
def echo_all(message):
|
||||
bot.reply_to(message, message.text)
|
||||
|
||||
bot.polling()
|
||||
|
||||
Now we rewrite it to use Telethon:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import TelegramClient, events
|
||||
|
||||
bot = TelegramClient('bot', 11111, 'a1b2c3d4').start(bot_token='TOKEN')
|
||||
|
||||
@bot.on(events.NewMessage(pattern='/start'))
|
||||
async def send_welcome(event):
|
||||
await event.reply('Howdy, how are you doing?')
|
||||
|
||||
@bot.on(events.NewMessage)
|
||||
async def echo_all(event):
|
||||
await event.reply(event.text)
|
||||
|
||||
bot.run_until_disconnected()
|
||||
|
||||
Key differences:
|
||||
|
||||
* Instead of doing ``bot.reply_to(message)``, we can do ``event.reply``.
|
||||
Note that the ``event`` behaves just like their ``message``.
|
||||
* Telethon also supports ``func=lambda m: True``, but it's not necessary.
|
||||
|
||||
|
||||
Migrating from aiogram
|
||||
----------------------
|
||||
|
||||
From their GitHub:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from aiogram import Bot, Dispatcher, executor, types
|
||||
|
||||
API_TOKEN = 'BOT TOKEN HERE'
|
||||
|
||||
# Initialize bot and dispatcher
|
||||
bot = Bot(token=API_TOKEN)
|
||||
dp = Dispatcher(bot)
|
||||
|
||||
@dp.message_handler(commands=['start'])
|
||||
async def send_welcome(message: types.Message):
|
||||
"""
|
||||
This handler will be called when client send `/start` command.
|
||||
"""
|
||||
await message.reply("Hi!\nI'm EchoBot!\nPowered by aiogram.")
|
||||
|
||||
@dp.message_handler(regexp='(^cat[s]?$|puss)')
|
||||
async def cats(message: types.Message):
|
||||
with open('data/cats.jpg', 'rb') as photo:
|
||||
await bot.send_photo(message.chat.id, photo, caption='Cats is here 😺',
|
||||
reply_to_message_id=message.message_id)
|
||||
|
||||
@dp.message_handler()
|
||||
async def echo(message: types.Message):
|
||||
await bot.send_message(message.chat.id, message.text)
|
||||
|
||||
if __name__ == '__main__':
|
||||
executor.start_polling(dp, skip_updates=True)
|
||||
|
||||
|
||||
After rewrite:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import TelegramClient, events
|
||||
|
||||
# Initialize bot and... just the bot!
|
||||
bot = TelegramClient('bot', 11111, 'a1b2c3d4').start(bot_token='TOKEN')
|
||||
|
||||
@bot.on(events.NewMessage(pattern='/start'))
|
||||
async def send_welcome(event):
|
||||
await event.reply('Howdy, how are you doing?')
|
||||
|
||||
@bot.on(events.NewMessage(pattern='(^cat[s]?$|puss)'))
|
||||
async def cats(event):
|
||||
await event.reply('Cats is here 😺', file='data/cats.jpg')
|
||||
|
||||
@bot.on(events.NewMessage)
|
||||
async def echo_all(event):
|
||||
await event.reply(event.text)
|
||||
|
||||
if __name__ == '__main__':
|
||||
bot.run_until_disconnected()
|
||||
|
||||
|
||||
Key differences:
|
||||
|
||||
* Telethon offers convenience methods to avoid retyping
|
||||
``bot.send_photo(message.chat.id, ...)`` all the time,
|
||||
and instead let you type ``event.reply``.
|
||||
* Sending files is **a lot** easier. The methods for sending
|
||||
photos, documents, audios, etc. are all the same!
|
||||
|
||||
Migrating from dumbot
|
||||
---------------------
|
||||
|
||||
Showcasing their subclassing example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from dumbot import Bot
|
||||
|
||||
class Subbot(Bot):
|
||||
async def init(self):
|
||||
self.me = await self.getMe()
|
||||
|
||||
async def on_update(self, update):
|
||||
await self.sendMessage(
|
||||
chat_id=update.message.chat.id,
|
||||
text='i am {}'.format(self.me.username)
|
||||
)
|
||||
|
||||
Subbot(token).run()
|
||||
|
||||
After rewriting:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import TelegramClient, events
|
||||
|
||||
class Subbot(TelegramClient):
|
||||
def __init__(self, *a, **kw):
|
||||
super().__init__(*a, **kw)
|
||||
self.add_event_handler(self.on_update, events.NewMessage)
|
||||
|
||||
async def connect():
|
||||
await super().connect()
|
||||
self.me = await self.get_me()
|
||||
|
||||
async def on_update(event):
|
||||
await event.reply('i am {}'.format(self.me.username))
|
||||
|
||||
bot = Subbot('bot', 11111, 'a1b2c3d4').start(bot_token='TOKEN')
|
||||
bot.run_until_disconnected()
|
||||
|
||||
|
||||
Key differences:
|
||||
|
||||
* Telethon method names are ``snake_case``.
|
||||
* dumbot does not offer friendly methods like ``update.reply``.
|
||||
* Telethon does not have an implicit ``on_update`` handler, so
|
||||
we need to manually register one.
|
||||
|
||||
|
||||
.. _Telegram Bot API: https://core.telegram.org/bots/api
|
||||
.. _Introduction to Bots: https://core.telegram.org/bots
|
||||
.. _Bot FAQ: https://core.telegram.org/bots/faq
|
||||
.. _tdlib: https://core.telegram.org/tdlib
|
||||
.. _MTProto: https://core.telegram.org/mtproto
|
||||
.. _MTProto vs HTTP Bot API: https://github.com/LonamiWebs/Telethon/wiki/MTProto-vs-HTTP-Bot-API
|
||||
.. _requests: https://pypi.org/project/requests/
|
||||
.. _python-telegram-bot: https://python-telegram-bot.readthedocs.io
|
||||
.. _pyTelegramBotAPI: https://github.com/eternnoir/pyTelegramBotAPI
|
||||
.. _aiohttp: https://docs.aiohttp.org/en/stable
|
||||
.. _aiogram: https://aiogram.readthedocs.io
|
||||
.. _dumbot: https://github.com/Lonami/dumbot
|
||||
.. _echobot.py: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/echobot.py
|
||||
|
|
@ -1,169 +0,0 @@
|
|||
.. _chats-channels:
|
||||
|
||||
=================
|
||||
Chats vs Channels
|
||||
=================
|
||||
|
||||
Telegram's raw API can get very confusing sometimes, in particular when it
|
||||
comes to talking about "chats", "channels", "groups", "megagroups", and all
|
||||
those concepts.
|
||||
|
||||
This section will try to explain what each of these concepts are.
|
||||
|
||||
|
||||
Chats
|
||||
=====
|
||||
|
||||
A ``Chat`` can be used to talk about either the common "subclass" that both
|
||||
chats and channels share, or the concrete :tl:`Chat` type.
|
||||
|
||||
Technically, both :tl:`Chat` and :tl:`Channel` are a form of the `Chat type`_.
|
||||
|
||||
**Most of the time**, the term :tl:`Chat` is used to talk about *small group
|
||||
chats*. When you create a group through an official application, this is the
|
||||
type that you get. Official applications refer to these as "Group".
|
||||
|
||||
Both the bot API and Telethon will add a minus sign (negate) the real chat ID
|
||||
so that you can tell at a glance, with just a number, the entity type.
|
||||
|
||||
For example, if you create a chat with :tl:`CreateChatRequest`, the real chat
|
||||
ID might be something like `123`. If you try printing it from a
|
||||
`message.chat_id` you will see `-123`. This ID helps Telethon know you're
|
||||
talking about a :tl:`Chat`.
|
||||
|
||||
|
||||
Channels
|
||||
========
|
||||
|
||||
Official applications create a *broadcast* channel when you create a new
|
||||
channel (used to broadcast messages, only administrators can post messages).
|
||||
|
||||
Official applications implicitly *migrate* an *existing* :tl:`Chat` to a
|
||||
*megagroup* :tl:`Channel` when you perform certain actions (exceed user limit,
|
||||
add a public username, set certain permissions, etc.).
|
||||
|
||||
A ``Channel`` can be created directly with :tl:`CreateChannelRequest`, as
|
||||
either a ``megagroup`` or ``broadcast``.
|
||||
|
||||
Official applications use the term "channel" **only** for broadcast channels.
|
||||
|
||||
The API refers to the different types of :tl:`Channel` with certain attributes:
|
||||
|
||||
* A **broadcast channel** is a :tl:`Channel` with the ``channel.broadcast``
|
||||
attribute set to `True`.
|
||||
|
||||
* A **megagroup channel** is a :tl:`Channel` with the ``channel.megagroup``
|
||||
attribute set to `True`. Official applications refer to this as "supergroup".
|
||||
|
||||
* A **gigagroup channel** is a :tl:`Channel` with the ``channel.gigagroup``
|
||||
attribute set to `True`. Official applications refer to this as "broadcast
|
||||
groups", and is used when a megagroup becomes very large and administrators
|
||||
want to transform it into something where only they can post messages.
|
||||
|
||||
|
||||
Both the bot API and Telethon will "concatenate" ``-100`` to the real chat ID
|
||||
so that you can tell at a glance, with just a number, the entity type.
|
||||
|
||||
For example, if you create a new broadcast channel, the real channel ID might
|
||||
be something like `456`. If you try printing it from a `message.chat_id` you
|
||||
will see `-1000000000456`. This ID helps Telethon know you're talking about a
|
||||
:tl:`Channel`.
|
||||
|
||||
|
||||
Converting IDs
|
||||
==============
|
||||
|
||||
You can convert between the "marked" identifiers (prefixed with a minus sign)
|
||||
and the real ones with ``utils.resolve_id``. It will return a tuple with the
|
||||
real ID, and the peer type (the class):
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import utils
|
||||
real_id, peer_type = utils.resolve_id(-1000000000456)
|
||||
|
||||
print(real_id) # 456
|
||||
print(peer_type) # <class 'telethon.tl.types.PeerChannel'>
|
||||
|
||||
peer = peer_type(real_id)
|
||||
print(peer) # PeerChannel(channel_id=456)
|
||||
|
||||
|
||||
The reverse operation can be done with ``utils.get_peer_id``:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
print(utils.get_peer_id(types.PeerChannel(456))) # -1000000000456
|
||||
|
||||
|
||||
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``:
|
||||
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
print(await client.get_peer_id('me')) # your id
|
||||
|
||||
|
||||
If there is no "mark" (no minus sign), Telethon will assume your identifier
|
||||
refers to a :tl:`User`. If this is **not** the case, you can manually fix it:
|
||||
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import types
|
||||
await client.send_message(types.PeerChannel(456), 'hello')
|
||||
# ^^^^^^^^^^^^^^^^^ explicit peer type
|
||||
|
||||
|
||||
A note on raw API
|
||||
=================
|
||||
|
||||
Certain methods only work on a :tl:`Chat`, and some others only work on a
|
||||
:tl:`Channel` (and these may only work in broadcast, or megagroup). Your code
|
||||
likely knows what it's working with, so it shouldn't be too much of an issue.
|
||||
|
||||
If you need to find the :tl:`Channel` from a :tl:`Chat` that migrated to it,
|
||||
access the `migrated_to` property:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# chat is a Chat
|
||||
channel = await client.get_entity(chat.migrated_to)
|
||||
# channel is now a Channel
|
||||
|
||||
Channels do not have a "migrated_from", but a :tl:`ChannelFull` does. You can
|
||||
use :tl:`GetFullChannelRequest` to obtain this:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import functions
|
||||
full = await client(functions.channels.GetFullChannelRequest(your_channel))
|
||||
full_channel = full.full_chat
|
||||
# full_channel is a ChannelFull
|
||||
print(full_channel.migrated_from_chat_id)
|
||||
|
||||
This way, you can also access the linked discussion megagroup of a broadcast channel:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
print(full_channel.linked_chat_id) # prints ID of linked discussion group or None
|
||||
|
||||
You do not need to use ``client.get_entity`` to access the
|
||||
``migrated_from_chat_id`` :tl:`Chat` or the ``linked_chat_id`` :tl:`Channel`.
|
||||
They are in the ``full.chats`` attribute:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
if full_channel.migrated_from_chat_id:
|
||||
migrated_from_chat = next(c for c in full.chats if c.id == full_channel.migrated_from_chat_id)
|
||||
print(migrated_from_chat.title)
|
||||
|
||||
if full_channel.linked_chat_id:
|
||||
linked_group = next(c for c in full.chats if c.id == full_channel.linked_chat_id)
|
||||
print(linked_group.username)
|
||||
|
||||
.. _Chat type: https://tl.telethon.dev/types/chat.html
|
||||
|
|
@ -1,313 +0,0 @@
|
|||
.. _entities:
|
||||
|
||||
========
|
||||
Entities
|
||||
========
|
||||
|
||||
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`.
|
||||
|
||||
.. 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**.
|
||||
|
||||
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
|
||||
`client.get_dialogs() <telethon.client.dialogs.DialogMethods.get_dialogs>`.
|
||||
If the peer is someone in a group, you would similarly
|
||||
`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.
|
||||
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.
|
||||
|
||||
|
||||
.. contents::
|
||||
|
||||
|
||||
What is an Entity?
|
||||
==================
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
.. note::
|
||||
|
||||
Remember that the phone number must be in your contact list before you
|
||||
can use it.
|
||||
|
||||
You should use, **from better to worse**:
|
||||
|
||||
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')
|
||||
|
||||
|
||||
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:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
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')
|
||||
|
||||
|
||||
Getting Entities
|
||||
================
|
||||
|
||||
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:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# (These examples assume you are inside an "async def")
|
||||
#
|
||||
# Dialogs are the "conversations you have open".
|
||||
# This method returns a list of Dialog, which
|
||||
# has the .entity attribute and other information.
|
||||
#
|
||||
# This part is IMPORTANT, because it fills the entity 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')
|
||||
|
||||
# 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)
|
||||
|
||||
# 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))
|
||||
|
||||
|
||||
.. 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.
|
||||
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
|
||||
==================
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
bases. In this case, `ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>`
|
||||
knows how to get the *chat* where a thing belongs to.
|
||||
|
||||
So, a `Message <telethon.tl.custom.message.Message>` is a
|
||||
`ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>`.
|
||||
That means you can do this:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
message.is_private
|
||||
message.chat_id
|
||||
await message.get_chat()
|
||||
# ...etc
|
||||
|
||||
`SenderGetter <telethon.tl.custom.sendergetter.SenderGetter>` is similar:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
message.user_id
|
||||
await message.get_input_sender()
|
||||
message.user
|
||||
# ...etc
|
||||
|
||||
Quite a few things implement them, so it makes sense to reuse the code.
|
||||
For example, all events (except raw updates) implement `ChatGetter
|
||||
<telethon.tl.custom.chatgetter.ChatGetter>` since all events occur
|
||||
in some chat.
|
||||
|
||||
|
||||
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
|
||||
applications"? Now do the same with the library. Use what applies:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# (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)
|
||||
|
||||
# Do you have a conversation open with them? Get dialogs.
|
||||
await client.get_dialogs()
|
||||
|
||||
# Are they participant of some group? Get them.
|
||||
await client.get_participants('username')
|
||||
|
||||
# Is the entity the original sender of a forwarded message? Get it.
|
||||
await client.get_messages('username', 100)
|
||||
|
||||
# NOW you can use the ID, anywhere!
|
||||
await client.send_message(123456, 'Hi!')
|
||||
|
||||
entity = await client.get_entity(123456)
|
||||
print(entity)
|
||||
|
||||
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.
|
||||
|
|
@ -1,155 +0,0 @@
|
|||
.. _rpc-errors:
|
||||
|
||||
==========
|
||||
RPC Errors
|
||||
==========
|
||||
|
||||
RPC stands for Remote Procedure Call, and when the library raises
|
||||
a ``RPCError``, it's because you have invoked some of the API
|
||||
methods incorrectly (wrong parameters, wrong permissions, or even
|
||||
something went wrong on Telegram's server).
|
||||
|
||||
You should import the errors from ``telethon.errors`` like so:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import errors
|
||||
|
||||
try:
|
||||
async with client.takeout() as takeout:
|
||||
...
|
||||
|
||||
except errors.TakeoutInitDelayError as e:
|
||||
# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ here we except TAKEOUT_INIT_DELAY
|
||||
print('Must wait', e.seconds, 'before takeout')
|
||||
|
||||
|
||||
There isn't any official list of all possible RPC errors, so the
|
||||
`list of known errors`_ is provided on a best-effort basis. When new methods
|
||||
are available, the list may be lacking since we simply don't know what errors
|
||||
can raise from them.
|
||||
|
||||
Once we do find out about a new error and what causes it, the list is
|
||||
updated, so if you see an error without a specific class, do report it
|
||||
(and what method caused it)!.
|
||||
|
||||
This list is used to generate documentation for the `raw API page`_.
|
||||
For example, if we want to know what errors can occur from
|
||||
`messages.sendMessage`_ we can simply navigate to its raw API page
|
||||
and find it has 24 known RPC errors at the time of writing.
|
||||
|
||||
|
||||
Base Errors
|
||||
===========
|
||||
|
||||
All the "base" errors are listed in :ref:`telethon-errors`.
|
||||
Any other more specific error will be a subclass of these.
|
||||
|
||||
If the library isn't aware of a specific error just yet, it will instead
|
||||
raise one of these superclasses. This means you may find stuff like this:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
telethon.errors.rpcbaseerrors.BadRequestError: RPCError 400: MESSAGE_POLL_CLOSED (caused by SendVoteRequest)
|
||||
|
||||
If you do, make sure to open an issue or send a pull request to update the
|
||||
`list of known errors`_.
|
||||
|
||||
|
||||
Common Errors
|
||||
=============
|
||||
|
||||
These are some of the errors you may normally need to deal with:
|
||||
|
||||
- ``FloodWaitError`` (420), the same request was repeated many times.
|
||||
Must wait ``.seconds`` (you can access this attribute). For example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
...
|
||||
from telethon import errors
|
||||
|
||||
try:
|
||||
messages = await client.get_messages(chat)
|
||||
print(messages[0].text)
|
||||
except errors.FloodWaitError as e:
|
||||
print('Have to sleep', e.seconds, 'seconds')
|
||||
time.sleep(e.seconds)
|
||||
|
||||
- ``SessionPasswordNeededError``, if you have setup two-steps
|
||||
verification on Telegram and are trying to sign in.
|
||||
- ``FilePartMissingError``, if you have tried to upload an empty file.
|
||||
- ``ChatAdminRequiredError``, you don't have permissions to perform
|
||||
said operation on a chat or channel. Try avoiding filters, i.e. when
|
||||
searching messages.
|
||||
|
||||
The generic classes for different error codes are:
|
||||
|
||||
- ``InvalidDCError`` (303), the request must be repeated on another DC.
|
||||
- ``BadRequestError`` (400), the request contained errors.
|
||||
- ``UnauthorizedError`` (401), the user is not authorized yet.
|
||||
- ``ForbiddenError`` (403), privacy violation error.
|
||||
- ``NotFoundError`` (404), make sure you're invoking ``Request``\ 's!
|
||||
|
||||
If the error is not recognised, it will only be an ``RPCError``.
|
||||
|
||||
You can refer to all errors from Python through the ``telethon.errors``
|
||||
module. If you don't know what attributes they have, try printing their
|
||||
dir (like ``print(dir(e))``).
|
||||
|
||||
|
||||
Attributes
|
||||
==========
|
||||
|
||||
Some of the errors carry additional data in them. When they look like
|
||||
``EMAIL_UNCONFIRMED_X``, the ``_X`` value will be accessible from the
|
||||
error instance. The current list of errors that do this is the following:
|
||||
|
||||
- ``EmailUnconfirmedError`` has ``.code_length``.
|
||||
- ``FileMigrateError`` has ``.new_dc``.
|
||||
- ``FilePartMissingError`` has ``.which``.
|
||||
- ``FloodTestPhoneWaitError`` has ``.seconds``.
|
||||
- ``FloodWaitError`` has ``.seconds``.
|
||||
- ``InterdcCallErrorError`` has ``.dc``.
|
||||
- ``InterdcCallRichErrorError`` has ``.dc``.
|
||||
- ``NetworkMigrateError`` has ``.new_dc``.
|
||||
- ``PhoneMigrateError`` has ``.new_dc``.
|
||||
- ``SlowModeWaitError`` has ``.seconds``.
|
||||
- ``TakeoutInitDelayError`` has ``.seconds``.
|
||||
- ``UserMigrateError`` has ``.new_dc``.
|
||||
|
||||
|
||||
Avoiding Limits
|
||||
===============
|
||||
|
||||
Don't spam. You won't get ``FloodWaitError`` or your account banned or
|
||||
deleted if you use the library *for legit use cases*. Make cool tools.
|
||||
Don't spam! Nobody knows the exact limits for all requests since they
|
||||
depend on a lot of factors, so don't bother asking.
|
||||
|
||||
Still, if you do have a legit use case and still get those errors, the
|
||||
library will automatically sleep when they are smaller than 60 seconds
|
||||
by default. You can set different "auto-sleep" thresholds:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client.flood_sleep_threshold = 0 # Don't auto-sleep
|
||||
client.flood_sleep_threshold = 24 * 60 * 60 # Sleep always
|
||||
|
||||
You can also except it and act as you prefer:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.errors import FloodWaitError
|
||||
try:
|
||||
...
|
||||
except FloodWaitError as e:
|
||||
print('Flood waited for', e.seconds)
|
||||
quit(1)
|
||||
|
||||
VoIP numbers are very limited, and some countries are more limited too.
|
||||
|
||||
|
||||
.. _list of known errors: https://github.com/LonamiWebs/Telethon/blob/v1/telethon_generator/data/errors.csv
|
||||
.. _raw API page: https://tl.telethon.dev/
|
||||
.. _messages.sendMessage: https://tl.telethon.dev/methods/messages/send_message.html
|
||||
|
|
@ -1,420 +0,0 @@
|
|||
.. _full-api:
|
||||
|
||||
============
|
||||
The Full API
|
||||
============
|
||||
|
||||
.. important::
|
||||
|
||||
While you have access to this, you should always use the friendly
|
||||
methods listed on :ref:`client-ref` unless you have a better reason
|
||||
not to, like a method not existing or you wanting more control.
|
||||
|
||||
.. contents::
|
||||
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
The :ref:`telethon-client` doesn't offer a method for every single request
|
||||
the Telegram API supports. However, it's very simple to *call* or *invoke*
|
||||
any request defined in Telegram's API.
|
||||
|
||||
This section will teach you how to use what Telethon calls the `TL reference`_.
|
||||
The linked page contains a list and a way to search through *all* types
|
||||
generated from the definition of Telegram's API (in ``.tl`` file format,
|
||||
hence the name). These types include requests and constructors.
|
||||
|
||||
.. note::
|
||||
|
||||
The reason to keep both https://tl.telethon.dev and this
|
||||
documentation alive is that the former allows instant search results
|
||||
as you type, and a "Copy import" button. If you like namespaces, you
|
||||
can also do ``from telethon.tl import types, functions``. Both work.
|
||||
|
||||
Telegram makes these ``.tl`` files public, which other implementations, such
|
||||
as Telethon, can also use to generate code. These files are versioned under
|
||||
what's called "layers". ``.tl`` files consist of thousands of definitions,
|
||||
and newer layers often add, change, or remove them. Each definition refers
|
||||
to either a Remote Procedure Call (RPC) function, or a type (which the
|
||||
`TL reference`_ calls "constructors", as they construct particular type
|
||||
instances).
|
||||
|
||||
As such, the `TL reference`_ is a good place to go to learn about all possible
|
||||
requests, types, and what they look like. If you're curious about what's been
|
||||
changed between layers, you can refer to the `TL diff`_ site.
|
||||
|
||||
|
||||
Navigating the TL reference
|
||||
===========================
|
||||
|
||||
Functions
|
||||
---------
|
||||
|
||||
"Functions" is the term used for the Remote Procedure Calls (RPC) that can be
|
||||
sent to Telegram to ask it to perform something (e.g. "send message"). These
|
||||
requests have an associated return type. These can be invoked ("called"):
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client = TelegramClient(...)
|
||||
function_instance = SomeRequest(...)
|
||||
|
||||
# Invoke the request
|
||||
returned_type = await client(function_instance)
|
||||
|
||||
Whenever you find the type for a function in the `TL reference`_, the page
|
||||
will contain the following information:
|
||||
|
||||
* What type of account can use the method. This information is regenerated
|
||||
from time to time (by attempting to invoke the function under both account
|
||||
types and finding out where it fails). Some requests can only be used by
|
||||
bot accounts, others by user accounts, and others by both.
|
||||
* The TL definition. This helps you get a feel for the what the function
|
||||
looks like. This is not Python code. It just contains the definition in
|
||||
a concise manner.
|
||||
* "Copy import" button. Does what it says: it will copy the necessary Python
|
||||
code to import the function to your system's clipboard for easy access.
|
||||
* Returns. The returned type. When you invoke the function, this is what the
|
||||
result will be. It also includes which of the constructors can be returned
|
||||
inline, to save you a click.
|
||||
* Parameters. The parameters accepted by the function, including their type,
|
||||
whether they expect a list, and whether they're optional.
|
||||
* Known RPC errors. A best-effort list of known errors the request may cause.
|
||||
This list is not complete and may be out of date, but should provide an
|
||||
overview of what could go wrong.
|
||||
* Example. Autogenerated example, showcasing how you may want to call it.
|
||||
Bear in mind that this is *autogenerated*. It may be spitting out non-sense.
|
||||
The goal of this example is not to show you everything you can do with the
|
||||
request, only to give you a feel for what it looks like to use it.
|
||||
|
||||
It is very important to click through the links and navigate to get the full
|
||||
picture. A specific page will show you what the specific function returns and
|
||||
needs as input parameters. But it may reference other types, so you need to
|
||||
navigate to those to learn what those contain or need.
|
||||
|
||||
Types
|
||||
-----
|
||||
|
||||
"Types" as understood by TL are not actually generated in Telethon.
|
||||
They would be the "abstract base class" of the constructors, but since Python
|
||||
is duck-typed, there is hardly any need to generate mostly unnecessary code.
|
||||
The page for a type contains:
|
||||
|
||||
* Constructors. Every type will have one or more constructors. These
|
||||
constructors *are* generated and can be immported and used.
|
||||
* Requests returning this type. A helpful way to find out "what requests can
|
||||
return this?". This is how you may learn what request you need to use to
|
||||
obtain a particular instance of a type.
|
||||
* Requests accepting this type as input. A helpful way to find out "what
|
||||
requests can use this type as one of their input parameters?". This is how
|
||||
you may learn where a type is used.
|
||||
* Other types containing this type. A helpful way to find out "where else
|
||||
does this type appear?". This is how you can walk back through nested
|
||||
objects.
|
||||
|
||||
Constructors
|
||||
------------
|
||||
|
||||
Constructors are used to create instances of a particular type, and are also
|
||||
returned when invoking requests. You will have to create instances yourself
|
||||
when invoking requests that need a particular type as input.
|
||||
The page for a constructor contains:
|
||||
|
||||
* Belongs to. The parent type. This is a link back to the types page for the
|
||||
specific constructor. It also contains the sibling constructors inline, to
|
||||
save you a click.
|
||||
* Members. Both the input parameters *and* fields the constructor contains.
|
||||
|
||||
|
||||
Using the TL reference
|
||||
======================
|
||||
|
||||
After you've found a request you want to send, a good start would be to simply
|
||||
copy and paste the autogenerated example into your script. Then you can simply
|
||||
tweak it to your needs.
|
||||
|
||||
If you want to do it from scratch, first, make sure to import the request into
|
||||
your code (either using the "Copy import" button near the top, or by manually
|
||||
spelling out the package under ``telethon.tl.functions.*``).
|
||||
|
||||
Then, start reading the parameters one by one. If the parameter cannot be
|
||||
omitted, you **will** need to specify it, so make sure to spell it out as
|
||||
an input parameter when constructing the request instance. Let's look at
|
||||
`PingRequest`_ for example. First, we copy the import:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.tl.functions import PingRequest
|
||||
|
||||
Then, we look at the parameters:
|
||||
|
||||
ping_id - long
|
||||
|
||||
A single parameter, and it's a long (a integer number with a large range of
|
||||
values). It doesn't say it can be omitted, so we must provide it, like so:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
PingRequest(
|
||||
ping_id=48641868471
|
||||
)
|
||||
|
||||
(In this case, the ping ID is a random number. You often have to guess what
|
||||
the parameter needs just by looking at the name.)
|
||||
|
||||
Now that we have our request, we can invoke it:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
response = await client(PingRequest(
|
||||
ping_id=48641868471
|
||||
))
|
||||
|
||||
To find out what ``response`` looks like, we can do as the autogenerated
|
||||
example suggests and "stringify" the result as a pretty-printed string:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
print(result.stringify())
|
||||
|
||||
This will print out the following:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
Pong(
|
||||
msg_id=781875678118,
|
||||
ping_id=48641868471
|
||||
)
|
||||
|
||||
Which is a very easy way to get a feel for a response. You should nearly
|
||||
always print the stringified result, at least once, when trying out requests,
|
||||
to get a feel for what the response may look like.
|
||||
|
||||
But of course, you don't need to do that. Without writing any code, you could
|
||||
have navigated through the "Returns" link to learn ``PingRequest`` returns a
|
||||
``Pong``, which only has one constructor, and the constructor has two members,
|
||||
``msg_id`` and ``ping_id``.
|
||||
|
||||
If you wanted to create your own ``Pong``, you would use both members as input
|
||||
parameters:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
my_pong = Pong(
|
||||
msg_id=781875678118,
|
||||
ping_id=48641868471
|
||||
)
|
||||
|
||||
(Yes, constructing object instances can use the same code that ``.stringify``
|
||||
would return!)
|
||||
|
||||
And if you wanted to access the ``msg_id`` member, you would simply access it
|
||||
like any other attribute access in Python:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
print(response.msg_id)
|
||||
|
||||
|
||||
Example walkthrough
|
||||
===================
|
||||
|
||||
Say `client.send_message()
|
||||
<telethon.client.messages.MessageMethods.send_message>` didn't exist,
|
||||
we could `use the search`_ to look for "message". There we would find
|
||||
:tl:`SendMessageRequest`, which we can work with.
|
||||
|
||||
Every request is a Python class, and has the parameters needed for you
|
||||
to invoke it. You can also call ``help(request)`` for information on
|
||||
what input parameters it takes. Remember to "Copy import to the
|
||||
clipboard", or your script won't be aware of this class! Now we have:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.tl.functions.messages import SendMessageRequest
|
||||
|
||||
If you're going to use a lot of these, you may do:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.tl import types, functions
|
||||
# We now have access to 'functions.messages.SendMessageRequest'
|
||||
|
||||
We see that this request must take at least two parameters, a ``peer``
|
||||
of type :tl:`InputPeer`, and a ``message`` which is just a Python
|
||||
`str`\ ing.
|
||||
|
||||
How can we retrieve this :tl:`InputPeer`? We have two options. We manually
|
||||
construct one, for instance:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.tl.types import InputPeerUser
|
||||
|
||||
peer = InputPeerUser(user_id, user_hash)
|
||||
|
||||
Or we call `client.get_input_entity()
|
||||
<telethon.client.users.UserMethods.get_input_entity>`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import telethon
|
||||
|
||||
async def main():
|
||||
peer = await client.get_input_entity('someone')
|
||||
|
||||
client.loop.run_until_complete(main())
|
||||
|
||||
.. note::
|
||||
|
||||
Remember that ``await`` must occur inside an ``async def``.
|
||||
Every full API example assumes you already know and do this.
|
||||
|
||||
|
||||
When you're going to invoke an API method, most require you to pass an
|
||||
:tl:`InputUser`, :tl:`InputChat`, or so on, this is why using
|
||||
`client.get_input_entity() <telethon.client.users.UserMethods.get_input_entity>`
|
||||
is more straightforward (and often immediate, if you've seen the user before,
|
||||
know their ID, etc.). If you also **need** to have information about the whole
|
||||
user, use `client.get_entity() <telethon.client.users.UserMethods.get_entity>`
|
||||
instead:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
entity = await client.get_entity('someone')
|
||||
|
||||
In the later case, when you use the entity, the library will cast it to
|
||||
its "input" version for you. If you already have the complete user and
|
||||
want to cache its input version so the library doesn't have to do this
|
||||
every time its used, simply call `telethon.utils.get_input_peer`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import utils
|
||||
peer = utils.get_input_peer(entity)
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
Since ``v0.16.2`` this is further simplified. The ``Request`` itself
|
||||
will call `client.get_input_entity
|
||||
<telethon.client.users.UserMethods.get_input_entity>` for you when
|
||||
required, but it's good to remember what's happening.
|
||||
|
||||
After this small parenthesis about `client.get_entity
|
||||
<telethon.client.users.UserMethods.get_entity>` versus
|
||||
`client.get_input_entity() <telethon.client.users.UserMethods.get_input_entity>`,
|
||||
we have everything we need. To invoke our
|
||||
request we do:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
result = await client(SendMessageRequest(peer, 'Hello there!'))
|
||||
|
||||
Message sent! Of course, this is only an example. There are over 250
|
||||
methods available as of layer 80, and you can use every single of them
|
||||
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!'
|
||||
))
|
||||
|
||||
|
||||
This can further be simplified to:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
result = await client(SendMessageRequest('username', 'Hello there!'))
|
||||
# Or even
|
||||
result = await client(SendMessageRequest(PeerChannel(id), 'Hello there!'))
|
||||
|
||||
.. note::
|
||||
|
||||
Note that some requests have a "hash" parameter. This is **not**
|
||||
your ``api_hash``! It likely isn't your self-user ``.access_hash`` either.
|
||||
|
||||
It's a special hash used by Telegram to only send a difference of new data
|
||||
that you don't already have with that request, so you can leave it to 0,
|
||||
and it should work (which means no hash is known yet).
|
||||
|
||||
For those requests having a "limit" parameter, you can often set it to
|
||||
zero to signify "return default amount". This won't work for all of them
|
||||
though, for instance, in "messages.search" it will actually return 0 items.
|
||||
|
||||
|
||||
Requests in Parallel
|
||||
====================
|
||||
|
||||
The library will automatically merge outgoing requests into a single
|
||||
*container*. Telegram's API supports sending multiple requests in a
|
||||
single container, which is faster because it has less overhead and
|
||||
the server can run them without waiting for others. You can also
|
||||
force using a container manually:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
async def main():
|
||||
|
||||
# Letting the library do it behind the scenes
|
||||
await asyncio.wait([
|
||||
client.send_message('me', 'Hello'),
|
||||
client.send_message('me', ','),
|
||||
client.send_message('me', 'World'),
|
||||
client.send_message('me', '.')
|
||||
])
|
||||
|
||||
# Manually invoking many requests at once
|
||||
await client([
|
||||
SendMessageRequest('me', 'Hello'),
|
||||
SendMessageRequest('me', ', '),
|
||||
SendMessageRequest('me', 'World'),
|
||||
SendMessageRequest('me', '.')
|
||||
])
|
||||
|
||||
Note that you cannot guarantee the order in which they are run.
|
||||
Try running the above code more than one time. You will see the
|
||||
order in which the messages arrive is different.
|
||||
|
||||
If you use the raw API (the first option), you can use ``ordered``
|
||||
to tell the server that it should run the requests sequentially.
|
||||
This will still be faster than going one by one, since the server
|
||||
knows all requests directly:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
await client([
|
||||
SendMessageRequest('me', 'Hello'),
|
||||
SendMessageRequest('me', ', '),
|
||||
SendMessageRequest('me', 'World'),
|
||||
SendMessageRequest('me', '.')
|
||||
], ordered=True)
|
||||
|
||||
If any of the requests fails with a Telegram error (not connection
|
||||
errors or any other unexpected events), the library will raise
|
||||
`telethon.errors.common.MultiError`. You can ``except`` this
|
||||
and still access the successful results:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.errors import MultiError
|
||||
|
||||
try:
|
||||
await client([
|
||||
SendMessageRequest('me', 'Hello'),
|
||||
SendMessageRequest('me', ''),
|
||||
SendMessageRequest('me', 'World')
|
||||
], ordered=True)
|
||||
except MultiError as e:
|
||||
# The first and third requests worked.
|
||||
first = e.results[0]
|
||||
third = e.results[2]
|
||||
# The second request failed.
|
||||
second = e.exceptions[1]
|
||||
|
||||
.. _TL reference: https://tl.telethon.dev
|
||||
.. _TL diff: https://diff.telethon.dev
|
||||
.. _PingRequest: https://tl.telethon.dev/methods/ping.html
|
||||
.. _use the search: https://tl.telethon.dev/?q=message&redirect=no
|
||||
|
|
@ -1,88 +0,0 @@
|
|||
======================
|
||||
String-based Debugging
|
||||
======================
|
||||
|
||||
Debugging is *really* important. Telegram's API is really big and there
|
||||
are a lot of things that you should know. Such as, what attributes or fields
|
||||
does a result have? Well, the easiest thing to do is printing it:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
entity = await client.get_entity('username')
|
||||
print(entity)
|
||||
|
||||
That will show a huge **string** similar to the following:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
Channel(id=1066197625, title='Telegram Usernames', photo=ChatPhotoEmpty(), date=datetime.datetime(2016, 12, 16, 15, 15, 43, tzinfo=datetime.timezone.utc), version=0, creator=False, left=True, broadcast=True, verified=True, megagroup=False, restricted=False, signatures=False, min=False, scam=False, has_link=False, has_geo=False, slowmode_enabled=False, access_hash=-6309373984955162244, username='username', restriction_reason=[], admin_rights=None, banned_rights=None, default_banned_rights=None, participants_count=None)
|
||||
|
||||
That's a lot of text. But as you can see, all the properties are there.
|
||||
So if you want the title you **don't use regex** or anything like
|
||||
splitting ``str(entity)`` to get what you want. You just access the
|
||||
attribute you need:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
title = entity.title
|
||||
|
||||
Can we get better than the shown string, though? Yes!
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
print(entity.stringify())
|
||||
|
||||
Will show a much better representation:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
Channel(
|
||||
id=1066197625,
|
||||
title='Telegram Usernames',
|
||||
photo=ChatPhotoEmpty(
|
||||
),
|
||||
date=datetime.datetime(2016, 12, 16, 15, 15, 43, tzinfo=datetime.timezone.utc),
|
||||
version=0,
|
||||
creator=False,
|
||||
left=True,
|
||||
broadcast=True,
|
||||
verified=True,
|
||||
megagroup=False,
|
||||
restricted=False,
|
||||
signatures=False,
|
||||
min=False,
|
||||
scam=False,
|
||||
has_link=False,
|
||||
has_geo=False,
|
||||
slowmode_enabled=False,
|
||||
access_hash=-6309373984955162244,
|
||||
username='username',
|
||||
restriction_reason=[
|
||||
],
|
||||
admin_rights=None,
|
||||
banned_rights=None,
|
||||
default_banned_rights=None,
|
||||
participants_count=None
|
||||
)
|
||||
|
||||
|
||||
Now it's easy to see how we could get, for example,
|
||||
the ``year`` value. It's inside ``date``:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
channel_year = entity.date.year
|
||||
|
||||
You don't need to print everything to see what all the possible values
|
||||
can be. You can just search in http://tl.telethon.dev/.
|
||||
|
||||
Remember that you can use Python's `isinstance
|
||||
<https://docs.python.org/3/library/functions.html#isinstance>`_
|
||||
to check the type of something. For example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import types
|
||||
|
||||
if isinstance(entity.photo, types.ChatPhotoEmpty):
|
||||
print('Channel has no photo')
|
||||
|
|
@ -1,228 +0,0 @@
|
|||
================
|
||||
Updates in Depth
|
||||
================
|
||||
|
||||
Properties vs. Methods
|
||||
======================
|
||||
|
||||
The event shown above acts just like a `custom.Message
|
||||
<telethon.tl.custom.message.Message>`, which means you
|
||||
can access all the properties it has, like ``.sender``.
|
||||
|
||||
**However** events are different to other methods in the client, like
|
||||
`client.get_messages <telethon.client.messages.MessageMethods.get_messages>`.
|
||||
Events *may not* send information about the sender or chat, which means it
|
||||
can be `None`, but all the methods defined in the client always have this
|
||||
information so it doesn't need to be re-fetched. For this reason, you have
|
||||
``get_`` methods, which will make a network call if necessary.
|
||||
|
||||
In short, you should do this:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@client.on(events.NewMessage)
|
||||
async def handler(event):
|
||||
# event.input_chat may be None, use event.get_input_chat()
|
||||
chat = await event.get_input_chat()
|
||||
sender = await event.get_sender()
|
||||
buttons = await event.get_buttons()
|
||||
|
||||
async def main():
|
||||
async for message in client.iter_messages('me', 10):
|
||||
# Methods from the client always have these properties ready
|
||||
chat = message.input_chat
|
||||
sender = message.sender
|
||||
buttons = message.buttons
|
||||
|
||||
Notice, properties (`message.sender
|
||||
<telethon.tl.custom.message.Message.sender>`) don't need an ``await``, but
|
||||
methods (`message.get_sender
|
||||
<telethon.tl.custom.message.Message.get_sender>`) **do** need an ``await``,
|
||||
and you should use methods in events for these properties that may need network.
|
||||
|
||||
Events Without the client
|
||||
=========================
|
||||
|
||||
The code of your application starts getting big, so you decide to
|
||||
separate the handlers into different files. But how can you access
|
||||
the client from these files? You don't need to! Just `events.register
|
||||
<telethon.events.register>` them:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# handlers/welcome.py
|
||||
from telethon import events
|
||||
|
||||
@events.register(events.NewMessage('(?i)hello'))
|
||||
async def handler(event):
|
||||
client = event.client
|
||||
await event.respond('Hey!')
|
||||
await client.send_message('me', 'I said hello to someone')
|
||||
|
||||
|
||||
Registering events is a way of saying "this method is an event handler".
|
||||
You can use `telethon.events.is_handler` to check if any method is a handler.
|
||||
You can think of them as a different approach to Flask's blueprints.
|
||||
|
||||
It's important to note that this does **not** add the handler to any client!
|
||||
You never specified the client on which the handler should be used. You only
|
||||
declared that it is a handler, and its type.
|
||||
|
||||
To actually use the handler, you need to `client.add_event_handler
|
||||
<telethon.client.updates.UpdateMethods.add_event_handler>` to the
|
||||
client (or clients) where they should be added to:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# main.py
|
||||
from telethon import TelegramClient
|
||||
import handlers.welcome
|
||||
|
||||
with TelegramClient(...) as client:
|
||||
client.add_event_handler(handlers.welcome.handler)
|
||||
client.run_until_disconnected()
|
||||
|
||||
|
||||
This also means that you can register an event handler once and
|
||||
then add it to many clients without re-declaring the event.
|
||||
|
||||
|
||||
Events Without Decorators
|
||||
=========================
|
||||
|
||||
If for any reason you don't want to use `telethon.events.register`,
|
||||
you can explicitly pass the event handler to use to the mentioned
|
||||
`client.add_event_handler
|
||||
<telethon.client.updates.UpdateMethods.add_event_handler>`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import TelegramClient, events
|
||||
|
||||
async def handler(event):
|
||||
...
|
||||
|
||||
with TelegramClient(...) as client:
|
||||
client.add_event_handler(handler, events.NewMessage)
|
||||
client.run_until_disconnected()
|
||||
|
||||
|
||||
Similarly, you also have `client.remove_event_handler
|
||||
<telethon.client.updates.UpdateMethods.remove_event_handler>`
|
||||
and `client.list_event_handlers
|
||||
<telethon.client.updates.UpdateMethods.list_event_handlers>`.
|
||||
|
||||
The ``event`` argument is optional in all three methods and defaults to
|
||||
`events.Raw <telethon.events.raw.Raw>` for adding, and `None` when
|
||||
removing (so all callbacks would be removed).
|
||||
|
||||
.. note::
|
||||
|
||||
The ``event`` type is ignored in `client.add_event_handler
|
||||
<telethon.client.updates.UpdateMethods.add_event_handler>`
|
||||
if you have used `telethon.events.register` on the ``callback``
|
||||
before, since that's the point of using such method at all.
|
||||
|
||||
|
||||
Stopping Propagation of Updates
|
||||
===============================
|
||||
|
||||
There might be cases when an event handler is supposed to be used solitary and
|
||||
it makes no sense to process any other handlers in the chain. For this case,
|
||||
it is possible to raise a `telethon.events.StopPropagation` exception which
|
||||
will cause the propagation of the update through your handlers to stop:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.events import StopPropagation
|
||||
|
||||
@client.on(events.NewMessage)
|
||||
async def _(event):
|
||||
# ... some conditions
|
||||
await event.delete()
|
||||
|
||||
# Other handlers won't have an event to work with
|
||||
raise StopPropagation
|
||||
|
||||
@client.on(events.NewMessage)
|
||||
async def _(event):
|
||||
# Will never be reached, because it is the second handler
|
||||
# in the chain.
|
||||
pass
|
||||
|
||||
|
||||
Remember to check :ref:`telethon-events` if you're looking for
|
||||
the methods reference.
|
||||
|
||||
Understanding asyncio
|
||||
=====================
|
||||
|
||||
|
||||
With `asyncio`, the library has several tasks running in the background.
|
||||
One task is used for sending requests, another task is used to receive them,
|
||||
and a third one is used to handle updates.
|
||||
|
||||
To handle updates, you must keep your script running. You can do this in
|
||||
several ways. For instance, if you are *not* running `asyncio`'s event
|
||||
loop, you should use `client.run_until_disconnected
|
||||
<telethon.client.updates.UpdateMethods.run_until_disconnected>`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import asyncio
|
||||
from telethon import TelegramClient
|
||||
|
||||
client = TelegramClient(...)
|
||||
...
|
||||
client.run_until_disconnected()
|
||||
|
||||
|
||||
Behind the scenes, this method is ``await``'ing on the `client.disconnected
|
||||
<telethon.client.telegrambaseclient.TelegramBaseClient.disconnected>` property,
|
||||
so the code above and the following are equivalent:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import asyncio
|
||||
from telethon import TelegramClient
|
||||
|
||||
client = TelegramClient(...)
|
||||
|
||||
async def main():
|
||||
await client.disconnected
|
||||
|
||||
asyncio.run(main())
|
||||
|
||||
|
||||
You could also run `client.disconnected
|
||||
<telethon.client.telegrambaseclient.TelegramBaseClient.disconnected>`
|
||||
until it completed.
|
||||
|
||||
But if you don't want to ``await``, then you should know what you want
|
||||
to be doing instead! What matters is that you shouldn't let your script
|
||||
die. If you don't care about updates, you don't need any of this.
|
||||
|
||||
Notice that unlike `client.disconnected
|
||||
<telethon.client.telegrambaseclient.TelegramBaseClient.disconnected>`,
|
||||
`client.run_until_disconnected
|
||||
<telethon.client.updates.UpdateMethods.run_until_disconnected>` will
|
||||
handle ``KeyboardInterrupt`` for you. This method is special and can
|
||||
also be ran while the loop is running, so you can do this:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
async def main():
|
||||
await client.run_until_disconnected()
|
||||
|
||||
loop.run_until_complete(main())
|
||||
|
||||
Sequential Updates
|
||||
==================
|
||||
|
||||
If you need to process updates sequentially (i.e. not in parallel),
|
||||
you should set ``sequential_updates=True`` when creating the client:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
with TelegramClient(..., sequential_updates=True) as client:
|
||||
...
|
||||
|
|
@ -20,13 +20,14 @@
|
|||
import re
|
||||
import os
|
||||
import sys
|
||||
|
||||
sys.path.insert(0, os.path.abspath(os.curdir))
|
||||
sys.path.insert(0, os.path.abspath(os.pardir))
|
||||
|
||||
|
||||
root = os.path.abspath(os.path.join(__file__, os.path.pardir, os.path.pardir))
|
||||
|
||||
tl_ref_url = 'https://tl.telethon.dev'
|
||||
tl_ref_url = 'https://lonamiwebs.github.io/Telethon'
|
||||
|
||||
|
||||
# -- General configuration ------------------------------------------------
|
||||
|
||||
|
|
@ -39,15 +40,9 @@ tl_ref_url = 'https://tl.telethon.dev'
|
|||
# ones.
|
||||
extensions = [
|
||||
'sphinx.ext.autodoc',
|
||||
'sphinx.ext.autosummary',
|
||||
'sphinx.ext.intersphinx',
|
||||
'custom_roles'
|
||||
]
|
||||
|
||||
intersphinx_mapping = {
|
||||
'python': ('https://docs.python.org/3', None)
|
||||
}
|
||||
|
||||
# Change the default role so we can avoid prefixing everything with :obj:
|
||||
default_role = "py:obj"
|
||||
|
||||
|
|
@ -65,7 +60,7 @@ master_doc = 'index'
|
|||
|
||||
# General information about the project.
|
||||
project = 'Telethon'
|
||||
copyright = '2017 - 2019, Lonami'
|
||||
copyright = '2017, Lonami'
|
||||
author = 'Lonami'
|
||||
|
||||
# The version info for the project you're documenting, acts as replacement for
|
||||
|
|
@ -85,7 +80,7 @@ release = version
|
|||
#
|
||||
# This is also used if you do content translation via gettext catalogs.
|
||||
# Usually you set "language" from the command line for these cases.
|
||||
language = 'en'
|
||||
language = None
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
|
|
@ -93,30 +88,12 @@ language = 'en'
|
|||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use.
|
||||
pygments_style = 'friendly'
|
||||
pygments_style = 'sphinx'
|
||||
|
||||
# If true, `todo` and `todoList` produce output, else they produce nothing.
|
||||
todo_include_todos = False
|
||||
|
||||
|
||||
def skip(app, what, name, obj, would_skip, options):
|
||||
if name.endswith('__'):
|
||||
# We want to show special methods names, except some which add clutter
|
||||
return name in {
|
||||
'__init__',
|
||||
'__abstractmethods__',
|
||||
'__module__',
|
||||
'__doc__',
|
||||
'__dict__'
|
||||
}
|
||||
|
||||
return would_skip
|
||||
|
||||
|
||||
def setup(app):
|
||||
app.connect("autodoc-skip-member", skip)
|
||||
|
||||
|
||||
# -- Options for HTML output ----------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
|
|
@ -137,7 +114,7 @@ html_theme_options = {
|
|||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
# html_static_path = ['_static']
|
||||
html_static_path = ['_static']
|
||||
|
||||
# Custom sidebar templates, must be a dictionary that maps document names
|
||||
# to template names.
|
||||
|
|
@ -209,3 +186,5 @@ texinfo_documents = [
|
|||
'Miscellaneous'),
|
||||
]
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -28,7 +28,6 @@ def make_link_node(rawtext, app, name, options):
|
|||
return node
|
||||
|
||||
|
||||
# noinspection PyUnusedLocal
|
||||
def tl_role(name, rawtext, text, lineno, inliner, options=None, content=None):
|
||||
"""
|
||||
Link to the TL reference.
|
||||
|
|
@ -46,6 +45,8 @@ def tl_role(name, rawtext, text, lineno, inliner, options=None, content=None):
|
|||
"""
|
||||
if options is None:
|
||||
options = {}
|
||||
if content is None:
|
||||
content = []
|
||||
|
||||
# TODO Report error on type not found?
|
||||
# Usage:
|
||||
|
|
@ -62,6 +63,7 @@ def setup(app):
|
|||
|
||||
:param app: Sphinx application context.
|
||||
"""
|
||||
app.info('Initializing TL reference plugin')
|
||||
app.add_role('tl', tl_role)
|
||||
app.add_config_value('tl_ref_url', None, 'env')
|
||||
return
|
||||
|
|
|
|||
|
|
@ -1,13 +0,0 @@
|
|||
===============================
|
||||
Telegram API in Other Languages
|
||||
===============================
|
||||
|
||||
Telethon was made for **Python**, and it has inspired other libraries such as
|
||||
`gramjs <https://github.com/gram-js/gramjs>`__ (JavaScript) and `grammers
|
||||
<https://github.com/Lonami/grammers>`__ (Rust). But there is a lot more beyond
|
||||
those, made independently by different developers.
|
||||
|
||||
If you're looking for something like Telethon but in a different programming
|
||||
language, head over to `Telegram API in Other Languages in the official wiki
|
||||
<https://github.com/LonamiWebs/Telethon/wiki/Telegram-API-in-Other-Languages>`__
|
||||
for a (mostly) up-to-date list.
|
||||
|
|
@ -1,87 +0,0 @@
|
|||
=====
|
||||
Tests
|
||||
=====
|
||||
|
||||
Telethon uses `Pytest <https://pytest.org/>`__, for testing, `Tox
|
||||
<https://tox.readthedocs.io/en/latest/>`__ for environment setup, and
|
||||
`pytest-asyncio <https://pypi.org/project/pytest-asyncio/>`__ and `pytest-cov
|
||||
<https://pytest-cov.readthedocs.io/en/latest/>`__ for asyncio and
|
||||
`coverage <https://coverage.readthedocs.io/>`__ integration.
|
||||
|
||||
While reading the full documentation for these is probably a good idea, there
|
||||
is a lot to read, so a brief summary of these tools is provided below for
|
||||
convienience.
|
||||
|
||||
Brief Introduction to Pytest
|
||||
============================
|
||||
|
||||
`Pytest <https://pytest.org/>`__ is a tool for discovering and running python
|
||||
tests, as well as allowing modular reuse of test setup code using fixtures.
|
||||
|
||||
Most Pytest tests will look something like this::
|
||||
|
||||
from module import my_thing, my_other_thing
|
||||
|
||||
def test_my_thing(fixture):
|
||||
assert my_thing(fixture) == 42
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_my_thing(event_loop):
|
||||
assert await my_other_thing(loop=event_loop) == 42
|
||||
|
||||
Note here:
|
||||
|
||||
1. The test imports one specific function. The role of unit tests is to test
|
||||
that the implementation of some unit, like a function or class, works.
|
||||
It's role is not so much to test that components interact well with each
|
||||
other. I/O, such as connecting to remote servers, should be avoided. This
|
||||
helps with quickly identifying the source of an error, finding silent
|
||||
breakage, and makes it easier to cover all possible code paths.
|
||||
|
||||
System or integration tests can also be useful, but are currently out of
|
||||
scope of Telethon's automated testing.
|
||||
|
||||
2. A function ``test_my_thing`` is declared. Pytest searches for files
|
||||
starting with ``test_``, classes starting with ``Test`` and executes any
|
||||
functions or methods starting with ``test_`` it finds.
|
||||
|
||||
3. The function is declared with a parameter ``fixture``. Fixtures are used to
|
||||
request things required to run the test, such as temporary directories,
|
||||
free TCP ports, Connections, etc. Fixtures are declared by simply adding
|
||||
the fixture name as parameter. A full list of available fixtures can be
|
||||
found with the ``pytest --fixtures`` command.
|
||||
|
||||
4. The test uses a simple ``assert`` to test some condition is valid. Pytest
|
||||
uses some magic to ensure that the errors from this are readable and easy
|
||||
to debug.
|
||||
|
||||
5. The ``pytest.mark.asyncio`` fixture is provided by ``pytest-asyncio``. It
|
||||
starts a loop and executes a test function as coroutine. This should be
|
||||
used for testing asyncio code. It also declares the ``event_loop``
|
||||
fixture, which will request an ``asyncio`` event loop.
|
||||
|
||||
Brief Introduction to Tox
|
||||
=========================
|
||||
|
||||
`Tox <https://tox.readthedocs.io/en/latest/>`__ is a tool for automated setup
|
||||
of virtual environments for testing. While the tests can be run directly by
|
||||
just running ``pytest``, this only tests one specific python version in your
|
||||
existing environment, which will not catch e.g. undeclared dependencies, or
|
||||
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.
|
||||
|
||||
Brief Introduction to Pytest-cov
|
||||
================================
|
||||
|
||||
Coverage is a useful metric for testing. It measures the lines of code and
|
||||
branches that are exercised by the tests. The higher the coverage, the more
|
||||
likely it is that any coding errors will be caught by the tests.
|
||||
|
||||
A brief coverage report can be generated with the ``--cov`` option to ``tox``,
|
||||
which will be passed on to ``pytest``. Additionally, the very useful HTML
|
||||
report can be generated with ``--cov --cov-report=html``, which contains a
|
||||
browsable copy of the source code, annotated with coverage information for each
|
||||
line.
|
||||
|
|
@ -1,128 +0,0 @@
|
|||
===============================
|
||||
Working with Chats and Channels
|
||||
===============================
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
These examples assume you have read :ref:`full-api`.
|
||||
|
||||
.. contents::
|
||||
|
||||
|
||||
Joining a chat or channel
|
||||
=========================
|
||||
|
||||
Note that :tl:`Chat` are normal groups, and :tl:`Channel` are a
|
||||
special form of :tl:`Chat`, which can also be super-groups if
|
||||
their ``megagroup`` member is `True`.
|
||||
|
||||
|
||||
Joining a public channel
|
||||
========================
|
||||
|
||||
Once you have the :ref:`entity <entities>` of the channel you want to join
|
||||
to, you can make use of the :tl:`JoinChannelRequest` to join such channel:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.tl.functions.channels import JoinChannelRequest
|
||||
await client(JoinChannelRequest(channel))
|
||||
|
||||
# In the same way, you can also leave such channel
|
||||
from telethon.tl.functions.channels import LeaveChannelRequest
|
||||
await client(LeaveChannelRequest(input_channel))
|
||||
|
||||
|
||||
For more on channels, check the `channels namespace`__.
|
||||
|
||||
|
||||
__ https://tl.telethon.dev/methods/channels/index.html
|
||||
|
||||
|
||||
Joining a private chat or channel
|
||||
=================================
|
||||
|
||||
If all you have is a link like this one:
|
||||
``https://t.me/joinchat/AAAAAFFszQPyPEZ7wgxLtd``, you already have
|
||||
enough information to join! The part after the
|
||||
``https://t.me/joinchat/``, this is, ``AAAAAFFszQPyPEZ7wgxLtd`` on this
|
||||
example, is the ``hash`` of the chat or channel. Now you can use
|
||||
:tl:`ImportChatInviteRequest` as follows:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.tl.functions.messages import ImportChatInviteRequest
|
||||
updates = await client(ImportChatInviteRequest('AAAAAEHbEkejzxUjAUCfYg'))
|
||||
|
||||
|
||||
Adding someone else to such chat or channel
|
||||
===========================================
|
||||
|
||||
If you don't want to add yourself, maybe because you're already in,
|
||||
you can always add someone else with the :tl:`AddChatUserRequest`, which
|
||||
use is very straightforward, or :tl:`InviteToChannelRequest` for channels:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# For normal chats
|
||||
from telethon.tl.functions.messages import AddChatUserRequest
|
||||
|
||||
# Note that ``user_to_add`` is NOT the name of the parameter.
|
||||
# It's the user you want to add (``user_id=user_to_add``).
|
||||
await client(AddChatUserRequest(
|
||||
chat_id,
|
||||
user_to_add,
|
||||
fwd_limit=10 # Allow the user to see the 10 last messages
|
||||
))
|
||||
|
||||
# For channels (which includes megagroups)
|
||||
from telethon.tl.functions.channels import InviteToChannelRequest
|
||||
|
||||
await client(InviteToChannelRequest(
|
||||
channel,
|
||||
[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
|
||||
===============================
|
||||
|
||||
If you don't need to join but rather check whether it's a group or a
|
||||
channel, you can use the :tl:`CheckChatInviteRequest`, which takes in
|
||||
the hash of said channel or group.
|
||||
|
||||
|
||||
Increasing View Count in a Channel
|
||||
==================================
|
||||
|
||||
It has been asked `quite`__ `a few`__ `times`__ (really, `many`__), and
|
||||
while I don't understand why so many people ask this, the solution is to
|
||||
use :tl:`GetMessagesViewsRequest`, setting ``increment=True``:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
|
||||
# Obtain `channel' through dialogs or through client.get_entity() or anyhow.
|
||||
# Obtain `msg_ids' through `.get_messages()` or anyhow. Must be a list.
|
||||
|
||||
await client(GetMessagesViewsRequest(
|
||||
peer=channel,
|
||||
id=msg_ids,
|
||||
increment=True
|
||||
))
|
||||
|
||||
|
||||
Note that you can only do this **once or twice a day** per account,
|
||||
running this in a loop will obviously not increase the views forever
|
||||
unless you wait a day between each iteration. If you run it any sooner
|
||||
than that, the views simply won't be increased.
|
||||
|
||||
__ https://github.com/LonamiWebs/Telethon/issues/233
|
||||
__ https://github.com/LonamiWebs/Telethon/issues/305
|
||||
__ https://github.com/LonamiWebs/Telethon/issues/409
|
||||
__ https://github.com/LonamiWebs/Telethon/issues/447
|
||||
|
|
@ -1,17 +0,0 @@
|
|||
=================
|
||||
A Word of Warning
|
||||
=================
|
||||
|
||||
Full API is **not** how you are intended to use the library. You **should**
|
||||
always prefer the :ref:`client-ref`. However, not everything is implemented
|
||||
as a friendly method, so full API is your last resort.
|
||||
|
||||
If you select a method in :ref:`client-ref`, you will most likely find an
|
||||
example for that method. This is how you are intended to use the library.
|
||||
|
||||
Full API **will** break between different minor versions of the library,
|
||||
since Telegram changes very often. The friendly methods will be kept
|
||||
compatible between major versions.
|
||||
|
||||
If you need to see real-world examples, please refer to the
|
||||
`wiki page of projects using Telethon <https://github.com/LonamiWebs/Telethon/wiki/Projects-using-Telethon>`__.
|
||||
|
|
@ -1,13 +0,0 @@
|
|||
=====================
|
||||
Working with messages
|
||||
=====================
|
||||
|
||||
.. note::
|
||||
|
||||
These examples assume you have read :ref:`full-api`.
|
||||
|
||||
This section has been `moved to the wiki`_, where it can be easily edited as new
|
||||
features arrive and the API changes. Please refer to the linked page to learn how
|
||||
to send spoilers, custom emoji, stickers, react to messages, and more things.
|
||||
|
||||
.. _moved to the wiki: https://github.com/LonamiWebs/Telethon/wiki/Sending-more-than-just-messages
|
||||
230
readthedocs/extra/advanced-usage/accessing-the-full-api.rst
Normal file
230
readthedocs/extra/advanced-usage/accessing-the-full-api.rst
Normal file
|
|
@ -0,0 +1,230 @@
|
|||
.. _accessing-the-full-api:
|
||||
|
||||
======================
|
||||
Accessing the Full API
|
||||
======================
|
||||
|
||||
.. important::
|
||||
|
||||
While you have access to this, you should always use the friendly
|
||||
methods listed on :ref:`telethon-client` unless you have a better
|
||||
reason not to, like a method not existing or you wanting more control.
|
||||
|
||||
|
||||
The :ref:`TelegramClient <telethon-client>` doesn't offer a method for
|
||||
every single request the Telegram API supports. However, it's very simple to
|
||||
*call* or *invoke* any request. Whenever you need something, don't forget to
|
||||
`check the documentation`__ and look for the `method you need`__. There you
|
||||
can go through a sorted list of everything you can do.
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
The reason to keep both https://lonamiwebs.github.io/Telethon and this
|
||||
documentation alive is that the former allows instant search results
|
||||
as you type, and a "Copy import" button. If you like namespaces, you
|
||||
can also do ``from telethon.tl import types, functions``. Both work.
|
||||
|
||||
|
||||
.. important::
|
||||
|
||||
All the examples in this documentation assume that you have
|
||||
``from telethon import sync`` or ``import telethon.sync`` for the
|
||||
sake of simplicity and that you understand what it does (see
|
||||
:ref:`compatibility-and-convenience` for more). Simply add
|
||||
either line at the beginning of your project and it will work.
|
||||
|
||||
|
||||
You should also refer to the documentation to see what the objects
|
||||
(constructors) Telegram returns look like. Every constructor inherits
|
||||
from a common type, and that's the reason for this distinction.
|
||||
|
||||
Say `client.send_message
|
||||
<telethon.client.messages.MessageMethods.send_message>` didn't exist,
|
||||
we could use the `search`__ to look for "message". There we would find
|
||||
:tl:`SendMessageRequest`, which we can work with.
|
||||
|
||||
Every request is a Python class, and has the parameters needed for you
|
||||
to invoke it. You can also call ``help(request)`` for information on
|
||||
what input parameters it takes. Remember to "Copy import to the
|
||||
clipboard", or your script won't be aware of this class! Now we have:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.tl.functions.messages import SendMessageRequest
|
||||
|
||||
If you're going to use a lot of these, you may do:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.tl import types, functions
|
||||
# We now have access to 'functions.messages.SendMessageRequest'
|
||||
|
||||
We see that this request must take at least two parameters, a ``peer``
|
||||
of type :tl:`InputPeer`, and a ``message`` which is just a Python
|
||||
``str``\ ing.
|
||||
|
||||
How can we retrieve this :tl:`InputPeer`? We have two options. We manually
|
||||
construct one, for instance:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.tl.types import InputPeerUser
|
||||
|
||||
peer = InputPeerUser(user_id, user_hash)
|
||||
|
||||
Or we call `client.get_input_entity
|
||||
<telethon.client.users.UserMethods.get_input_entity>`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import telethon.sync
|
||||
peer = client.get_input_entity('someone')
|
||||
|
||||
|
||||
When you're going to invoke an API method, most require you to pass an
|
||||
:tl:`InputUser`, :tl:`InputChat`, or so on, this is why using
|
||||
`client.get_input_entity <telethon.client.users.UserMethods.get_input_entity>`
|
||||
is more straightforward (and often immediate, if you've seen the user before,
|
||||
know their ID, etc.). If you also **need** to have information about the whole
|
||||
user, use `client.get_entity <telethon.client.users.UserMethods.get_entity>`
|
||||
instead:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
entity = client.get_entity('someone')
|
||||
|
||||
In the later case, when you use the entity, the library will cast it to
|
||||
its "input" version for you. If you already have the complete user and
|
||||
want to cache its input version so the library doesn't have to do this
|
||||
every time its used, simply call `telethon.utils.get_input_peer`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import utils
|
||||
peer = utils.get_input_peer(entity)
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
Since ``v0.16.2`` this is further simplified. The ``Request`` itself
|
||||
will call `client.get_input_entity
|
||||
<telethon.client.users.UserMethods.get_input_entity>` for you when
|
||||
required, but it's good to remember what's happening.
|
||||
|
||||
After this small parenthesis about `client.get_entity
|
||||
<telethon.client.users.UserMethods.get_entity>` versus
|
||||
`client.get_input_entity <telethon.client.users.UserMethods.get_input_entity>`,
|
||||
we have everything we need. To invoke our
|
||||
request we do:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
result = client(SendMessageRequest(peer, 'Hello there!'))
|
||||
# __call__ is an alias for client.invoke(request). Both will work
|
||||
|
||||
Message sent! Of course, this is only an example. There are over 250
|
||||
methods available as of layer 80, and you can use every single of them
|
||||
as you wish. Remember to use the right types! To sum up:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
result = client(SendMessageRequest(
|
||||
client.get_input_entity('username'), 'Hello there!'
|
||||
))
|
||||
|
||||
|
||||
This can further be simplified to:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
result = client(SendMessageRequest('username', 'Hello there!'))
|
||||
# Or even
|
||||
result = client(SendMessageRequest(PeerChannel(id), 'Hello there!'))
|
||||
|
||||
.. note::
|
||||
|
||||
Note that some requests have a "hash" parameter. This is **not**
|
||||
your ``api_hash``! It likely isn't your self-user ``.access_hash`` either.
|
||||
|
||||
It's a special hash used by Telegram to only send a difference of new data
|
||||
that you don't already have with that request, so you can leave it to 0,
|
||||
and it should work (which means no hash is known yet).
|
||||
|
||||
For those requests having a "limit" parameter, you can often set it to
|
||||
zero to signify "return default amount". This won't work for all of them
|
||||
though, for instance, in "messages.search" it will actually return 0 items.
|
||||
|
||||
|
||||
Requests in Parallel
|
||||
********************
|
||||
|
||||
The library will automatically merge outgoing requests into a single
|
||||
*container*. Telegram's API supports sending multiple requests in a
|
||||
single container, which is faster because it has less overhead and
|
||||
the server can run them without waiting for others. You can also
|
||||
force using a container manually:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
async def main():
|
||||
|
||||
# Letting the library do it behind the scenes
|
||||
await asyncio.wait([
|
||||
client.send_message('me', 'Hello'),
|
||||
client.send_message('me', ','),
|
||||
client.send_message('me', 'World'),
|
||||
client.send_message('me', '.')
|
||||
])
|
||||
|
||||
# Manually invoking many requests at once
|
||||
await client([
|
||||
SendMessageRequest('me', 'Hello'),
|
||||
SendMessageRequest('me', ', '),
|
||||
SendMessageRequest('me', 'World'),
|
||||
SendMessageRequest('me', '.')
|
||||
])
|
||||
|
||||
Note that you cannot guarantee the order in which they are run.
|
||||
Try running the above code more than one time. You will see the
|
||||
order in which the messages arrive is different.
|
||||
|
||||
If you use the raw API (the first option), you can use ``ordered``
|
||||
to tell the server that it should run the requests sequentially.
|
||||
This will still be faster than going one by one, since the server
|
||||
knows all requests directly:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client([
|
||||
SendMessageRequest('me', 'Hello'),
|
||||
SendMessageRequest('me', ', '),
|
||||
SendMessageRequest('me', 'World'),
|
||||
SendMessageRequest('me', '.')
|
||||
], ordered=True)
|
||||
|
||||
If any of the requests fails with a Telegram error (not connection
|
||||
errors or any other unexpected events), the library will raise
|
||||
`telethon.errors.common.MultiError`. You can ``except`` this
|
||||
and still access the successful results:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.errors import MultiError
|
||||
|
||||
try:
|
||||
client([
|
||||
SendMessageRequest('me', 'Hello'),
|
||||
SendMessageRequest('me', ''),
|
||||
SendMessageRequest('me', 'World')
|
||||
], ordered=True)
|
||||
except MultiError as e:
|
||||
# The first and third requests worked.
|
||||
first = e.results[0]
|
||||
third = e.results[2]
|
||||
# The second request failed.
|
||||
second = e.exceptions[1]
|
||||
|
||||
__ https://lonamiwebs.github.io/Telethon
|
||||
__ https://lonamiwebs.github.io/Telethon/methods/index.html
|
||||
__ https://lonamiwebs.github.io/Telethon/?q=message&redirect=no
|
||||
|
|
@ -8,23 +8,23 @@ Mastering asyncio
|
|||
|
||||
|
||||
What's asyncio?
|
||||
===============
|
||||
***************
|
||||
|
||||
`asyncio` is a Python 3's built-in library. This means it's already installed if
|
||||
asyncio_ is a Python 3's built-in library. This means it's already installed if
|
||||
you have Python 3. Since Python 3.5, it is convenient to work with asynchronous
|
||||
code. Before (Python 3.4) we didn't have ``async`` or ``await``, but now we do.
|
||||
|
||||
`asyncio` stands for *Asynchronous Input Output*. This is a very powerful
|
||||
asyncio_ stands for *Asynchronous Input Output*. This is a very powerful
|
||||
concept to use whenever you work IO. Interacting with the web or external
|
||||
APIs such as Telegram's makes a lot of sense this way.
|
||||
|
||||
|
||||
Why asyncio?
|
||||
============
|
||||
************
|
||||
|
||||
Asynchronous IO makes a lot of sense in a library like Telethon.
|
||||
You send a request to the server (such as "get some message"), and
|
||||
thanks to `asyncio`, your code won't block while a response arrives.
|
||||
thanks to asyncio_, your code won't block while a response arrives.
|
||||
|
||||
The alternative would be to spawn a thread for each update so that
|
||||
other code can run while the response arrives. That is *a lot* more
|
||||
|
|
@ -38,28 +38,28 @@ because tasks are smaller than threads, which are smaller than processes.
|
|||
|
||||
|
||||
What are asyncio basics?
|
||||
========================
|
||||
|
||||
The code samples below assume that you have Python 3.7 or greater installed.
|
||||
************************
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# First we need the asyncio library
|
||||
import asyncio
|
||||
|
||||
# Then we need a loop to work with
|
||||
loop = asyncio.get_event_loop()
|
||||
|
||||
# We also need something to run
|
||||
async def main():
|
||||
for char in 'Hello, world!\n':
|
||||
print(char, end='', flush=True)
|
||||
await asyncio.sleep(0.2)
|
||||
|
||||
# Then, we can create a new asyncio loop and use it to run our coroutine.
|
||||
# The creation and tear-down of the loop is hidden away from us.
|
||||
asyncio.run(main())
|
||||
# Then, we need to run the loop with a task
|
||||
loop.run_until_complete(main())
|
||||
|
||||
|
||||
What does telethon.sync do?
|
||||
===========================
|
||||
***************************
|
||||
|
||||
The moment you import any of these:
|
||||
|
||||
|
|
@ -96,12 +96,8 @@ 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_running_loop() # == client.loop
|
||||
loop = asyncio.get_event_loop()
|
||||
me = loop.run_until_complete(client.get_me())
|
||||
print(me.username)
|
||||
|
||||
|
|
@ -137,7 +133,7 @@ running, and if the loop is running, you must ``await`` things yourself:
|
|||
|
||||
|
||||
What are async, await and coroutines?
|
||||
=====================================
|
||||
*************************************
|
||||
|
||||
The ``async`` keyword lets you define asynchronous functions,
|
||||
also known as coroutines, and also iterate over asynchronous
|
||||
|
|
@ -158,10 +154,13 @@ loops or use ``async with``:
|
|||
|
||||
print(message.sender.username)
|
||||
|
||||
asyncio.run(main())
|
||||
# ^ this will create a new asyncio loop behind the scenes and tear it down
|
||||
# once the function returns. It will run the loop untiil main finishes.
|
||||
# You should only use this function if there is no other loop running.
|
||||
loop = asyncio.get_event_loop()
|
||||
# ^ this assigns the default event loop from the main thread to a variable
|
||||
|
||||
loop.run_until_complete(main())
|
||||
# ^ this runs the *entire* loop until the main() function finishes.
|
||||
# While the main() function does not finish, the loop will be running.
|
||||
# While the loop is running, you can't run it again.
|
||||
|
||||
|
||||
The ``await`` keyword blocks the *current* task, and the loop can run
|
||||
|
|
@ -181,14 +180,14 @@ concurrently:
|
|||
await asyncio.sleep(delay) # await tells the loop this task is "busy"
|
||||
print('world') # eventually the loop finishes all tasks
|
||||
|
||||
async def main():
|
||||
asyncio.create_task(world(2)) # create the world task, passing 2 as delay
|
||||
asyncio.create_task(hello(delay=1)) # another task, but with delay 1
|
||||
await asyncio.sleep(3) # wait for three seconds before exiting
|
||||
|
||||
loop = asyncio.get_event_loop() # get the default loop for the main thread
|
||||
loop.create_task(world(2)) # create the world task, passing 2 as delay
|
||||
loop.create_task(hello(delay=1)) # another task, but with delay 1
|
||||
try:
|
||||
# create a new temporary asyncio loop and use it to run main
|
||||
asyncio.run(main())
|
||||
# run the event loop forever; ctrl+c to stop it
|
||||
# we could also run the loop for three seconds:
|
||||
# loop.run_until_complete(asyncio.sleep(3))
|
||||
loop.run_forever()
|
||||
except KeyboardInterrupt:
|
||||
pass
|
||||
|
||||
|
|
@ -206,43 +205,36 @@ The same example, but without the comment noise:
|
|||
await asyncio.sleep(delay)
|
||||
print('world')
|
||||
|
||||
async def main():
|
||||
asyncio.create_task(world(2))
|
||||
asyncio.create_task(hello(delay=1))
|
||||
await asyncio.sleep(3)
|
||||
|
||||
try:
|
||||
asyncio.run(main())
|
||||
except KeyboardInterrupt:
|
||||
pass
|
||||
loop = asyncio.get_event_loop()
|
||||
loop.create_task(world(2))
|
||||
loop.create_task(hello(1))
|
||||
loop.run_until_complete(asyncio.sleep(3))
|
||||
|
||||
|
||||
Can I use threads?
|
||||
==================
|
||||
******************
|
||||
|
||||
Yes, you can, but you must understand that the loops themselves are
|
||||
not thread safe. and you must be sure to know what is happening. The
|
||||
easiest and cleanest option is to use `asyncio.run` to create and manage
|
||||
the new event loop for you:
|
||||
not thread safe. and you must be sure to know what is happening. You
|
||||
may want to create a loop in a new thread and make sure to pass it to
|
||||
the client:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import asyncio
|
||||
import threading
|
||||
|
||||
async def actual_work():
|
||||
client = TelegramClient(..., loop=loop)
|
||||
... # can use `await` here
|
||||
|
||||
def go():
|
||||
asyncio.run(actual_work())
|
||||
loop = asyncio.new_event_loop()
|
||||
client = TelegramClient(..., loop=loop)
|
||||
...
|
||||
|
||||
threading.Thread(target=go).start()
|
||||
|
||||
|
||||
Generally, **you don't need threads** unless you know what you're doing.
|
||||
Just create another task, as shown above. If you're using the Telethon
|
||||
with a library that uses threads, you must be careful to use `threading.Lock`
|
||||
with a library that uses threads, you must be careful to use ``threading.Lock``
|
||||
whenever you use the client, or enable the compatible mode. For that, see
|
||||
:ref:`compatibility-and-convenience`.
|
||||
|
||||
|
|
@ -252,17 +244,17 @@ You may have seen this error:
|
|||
|
||||
RuntimeError: There is no current event loop in thread 'Thread-1'.
|
||||
|
||||
It just means you didn't create a loop for that thread. Please refer to
|
||||
the ``asyncio`` documentation to correctly learn how to set the event loop
|
||||
for non-main threads.
|
||||
It just means you didn't create a loop for that thread, and if you don't
|
||||
pass a loop when creating the client, it uses ``asyncio.get_event_loop()``,
|
||||
which only works in the main thread.
|
||||
|
||||
|
||||
client.run_until_disconnected() blocks!
|
||||
=======================================
|
||||
***************************************
|
||||
|
||||
All of what `client.run_until_disconnected()
|
||||
<telethon.client.updates.UpdateMethods.run_until_disconnected>` does is
|
||||
run the `asyncio`'s event loop until the client is disconnected. That means
|
||||
run the asyncio_'s event loop until the client is disconnected. That means
|
||||
*the loop is running*. And if the loop is running, it will run all the tasks
|
||||
in it. So if you want to run *other* code, create tasks for it:
|
||||
|
||||
|
|
@ -282,19 +274,18 @@ in it. So if you want to run *other* code, create tasks for it:
|
|||
This creates a task for a clock that prints the time every second.
|
||||
You don't need to use `client.run_until_disconnected()
|
||||
<telethon.client.updates.UpdateMethods.run_until_disconnected>` either!
|
||||
You just need to make the loop is running, somehow. `loop.run_forever()
|
||||
<asyncio.loop.run_forever()>` and `loop.run_until_complete()
|
||||
<asyncio.loop.run_until_complete>` can also be used to run
|
||||
the loop, and Telethon will be happy with any approach.
|
||||
You just need to make the loop is running, somehow. ``asyncio.run_forever``
|
||||
and ``asyncio.run_until_complete`` can also be used to run the loop, and
|
||||
Telethon will be happy with any approach.
|
||||
|
||||
Of course, there are better tools to run code hourly or daily, see below.
|
||||
|
||||
|
||||
What else can asyncio do?
|
||||
=========================
|
||||
*************************
|
||||
|
||||
Asynchronous IO is a really powerful tool, as we've seen. There are plenty
|
||||
of other useful libraries that also use `asyncio` and that you can integrate
|
||||
of other useful libraries that also use asyncio_ and that you can integrate
|
||||
with Telethon.
|
||||
|
||||
* `aiohttp <https://github.com/aio-libs/aiohttp>`_ is like the infamous
|
||||
|
|
@ -312,26 +303,27 @@ you can run requests in parallel:
|
|||
|
||||
async def main():
|
||||
last, sent, download_path = await asyncio.gather(
|
||||
client.get_messages('telegram', 10),
|
||||
client.send_message('me', 'Using asyncio!'),
|
||||
client.download_profile_photo('telegram')
|
||||
client.get_messages('TelethonChat', 10),
|
||||
client.send_message('TelethonOfftopic', 'Hey guys!'),
|
||||
client.download_profile_photo('TelethonChat')
|
||||
)
|
||||
|
||||
loop.run_until_complete(main())
|
||||
|
||||
|
||||
This code will get the 10 last messages from `@telegram
|
||||
<https://t.me/telegram>`_, send one to the chat with yourself, and also
|
||||
download the profile photo of the channel. `asyncio` will run all these
|
||||
three tasks at the same time. You can run all the tasks you want this way.
|
||||
This code will get the 10 last messages from `@TelethonChat
|
||||
<https://t.me/TelethonChat>`_, send one to `@TelethonOfftopic
|
||||
<https://t.me/TelethonOfftopic>`_, and also download the profile
|
||||
photo of the main group. asyncio_ will run all these three tasks
|
||||
at the same time. You can run all the tasks you want this way.
|
||||
|
||||
A different way would be:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
loop.create_task(client.get_messages('telegram', 10))
|
||||
loop.create_task(client.send_message('me', 'Using asyncio!'))
|
||||
loop.create_task(client.download_profile_photo('telegram'))
|
||||
loop.create_task(client.get_messages('TelethonChat', 10))
|
||||
loop.create_task(client.send_message('TelethonOfftopic', 'Hey guys!'))
|
||||
loop.create_task(client.download_profile_photo('TelethonChat'))
|
||||
|
||||
They will run in the background as long as the loop is running too.
|
||||
|
||||
|
|
@ -347,7 +339,7 @@ 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
|
||||
|
|
@ -360,9 +352,11 @@ Using the client in a ``with`` block, `start
|
|||
all support this.
|
||||
|
||||
Where can I read more?
|
||||
======================
|
||||
**********************
|
||||
|
||||
`Check out my blog post
|
||||
<https://lonami.dev/blog/asyncio/>`_ about `asyncio`, which
|
||||
<https://lonamiwebs.github.io/blog/asyncio/>`_ about asyncio_, which
|
||||
has some more examples and pictures to help you understand what happens
|
||||
when the loop runs.
|
||||
|
||||
.. _asyncio: https://docs.python.org/3/library/asyncio.html
|
||||
338
readthedocs/extra/advanced-usage/mastering-telethon.rst
Normal file
338
readthedocs/extra/advanced-usage/mastering-telethon.rst
Normal file
|
|
@ -0,0 +1,338 @@
|
|||
.. _mastering-telethon:
|
||||
|
||||
==================
|
||||
Mastering Telethon
|
||||
==================
|
||||
|
||||
You've come far! In this section you will learn best practices, as well
|
||||
as how to fix some silly (yet common) errors you may have found. Let's
|
||||
start with a simple one.
|
||||
|
||||
Asyncio madness
|
||||
***************
|
||||
|
||||
We promise ``asyncio`` is worth learning. Take your time to learn it.
|
||||
It's a powerful tool that enables you to use this powerful library.
|
||||
You need to be comfortable with it if you want to master Telethon.
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
AttributeError: 'coroutine' object has no attribute 'id'
|
||||
|
||||
You probably had a previous version, upgraded, and expected everything
|
||||
to work. Remember, just add this line:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import telethon.sync
|
||||
|
||||
If you're inside an event handler you need to ``await`` **everything** that
|
||||
*makes a network request*. Getting users, sending messages, and nearly
|
||||
everything in the library needs access to the network, so they need to
|
||||
be awaited:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@client.on(events.NewMessage)
|
||||
async def handler(event):
|
||||
print((await event.get_sender()).username)
|
||||
|
||||
|
||||
You may want to read https://lonamiwebs.github.io/blog/asyncio/ to help
|
||||
you understand ``asyncio`` better. I'm open for `feedback
|
||||
<https://t.me/LonamiWebs>`_ regarding that blog post
|
||||
|
||||
Entities
|
||||
********
|
||||
|
||||
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. There is an entire section on this at :ref:`entities` due to their
|
||||
importance.
|
||||
|
||||
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.
|
||||
|
||||
You should use, **from better to worse**:
|
||||
|
||||
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 short, unlike in most bot API libraries where you use the ID, you
|
||||
**should not** use the ID *if* you have the input entity. This is OK:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
async def handler(event):
|
||||
await client.send_message(event.sender_id, 'Hi')
|
||||
|
||||
However, **this is better**:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
async def handler(event):
|
||||
await client.send_message(event.input_sender, 'Hi')
|
||||
|
||||
Note that this also works for `message <telethon.tl.custom.message.Message>`
|
||||
instead of ``event``. Telegram may not send the sender information, so if you
|
||||
want to be 99% confident that the above will work you should do this:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
async def handler(event):
|
||||
await client.send_message(await event.get_input_sender(), 'Hi')
|
||||
|
||||
Methods are able to make network requests to get information that
|
||||
could be missing. Properties will never make a network request.
|
||||
|
||||
Of course, it is convenient to IDs or usernames for most purposes. It will
|
||||
be fast enough and caching with `client.get_input_entity(...)
|
||||
<telethon.client.users.UserMethods.get_input_entity>` will
|
||||
be a micro-optimization. However it's worth knowing, and it
|
||||
will also let you know if the entity cannot be found beforehand.
|
||||
|
||||
.. note::
|
||||
|
||||
Sometimes Telegram doesn't send the access hash inside entities,
|
||||
so using `chat <telethon.tl.custom.chatgetter.ChatGetter.chat>`
|
||||
or `sender <telethon.tl.custom.sendergetter.SenderGetter.sender>`
|
||||
may not work, but `input_chat
|
||||
<telethon.tl.custom.chatgetter.ChatGetter.input_chat>`
|
||||
and `input_sender
|
||||
<telethon.tl.custom.sendergetter.SenderGetter.input_sender>`
|
||||
while making requests definitely will since that's what they exist
|
||||
for. If Telegram did not send information about the access hash,
|
||||
you will get something like "Invalid channel object" or
|
||||
"Invalid user object".
|
||||
|
||||
|
||||
Debugging
|
||||
*********
|
||||
|
||||
**Please enable logging**:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import logging
|
||||
logging.basicConfig(level=logging.WARNING)
|
||||
|
||||
Change it for ``logging.DEBUG`` if you are asked for logs. It will save you
|
||||
a lot of headaches and time when you work with events. This is for errors.
|
||||
|
||||
Debugging is *really* important. Telegram's API is really big and there
|
||||
is a lot of things that you should know. Such as, what attributes or fields
|
||||
does a result have? Well, the easiest thing to do is printing it:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
user = client.get_entity('Lonami')
|
||||
print(user)
|
||||
|
||||
That will show a huge line similar to the following:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
User(id=10885151, is_self=False, contact=False, mutual_contact=False, deleted=False, bot=False, bot_chat_history=False, bot_nochats=False, verified=False, restricted=False, min=False, bot_inline_geo=False, access_hash=123456789012345678, first_name='Lonami', last_name=None, username='Lonami', phone=None, photo=UserProfilePhoto(photo_id=123456789012345678, photo_small=FileLocation(dc_id=4, volume_id=1234567890, local_id=1234567890, secret=123456789012345678), photo_big=FileLocation(dc_id=4, volume_id=1234567890, local_id=1234567890, secret=123456789012345678)), status=UserStatusOffline(was_online=datetime.datetime(2018, 1, 2, 3, 4, 5, tzinfo=datetime.timezone.utc)), bot_info_version=None, restriction_reason=None, bot_inline_placeholder=None, lang_code=None)
|
||||
|
||||
That's a lot of text. But as you can see, all the properties are there.
|
||||
So if you want the username you **don't use regex** or anything like
|
||||
splitting ``str(user)`` to get what you want. You just access the
|
||||
attribute you need:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
username = user.username
|
||||
|
||||
Can we get better than the shown string, though? Yes!
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
print(user.stringify())
|
||||
|
||||
Will show a much better:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
User(
|
||||
id=10885151,
|
||||
is_self=False,
|
||||
contact=False,
|
||||
mutual_contact=False,
|
||||
deleted=False,
|
||||
bot=False,
|
||||
bot_chat_history=False,
|
||||
bot_nochats=False,
|
||||
verified=False,
|
||||
restricted=False,
|
||||
min=False,
|
||||
bot_inline_geo=False,
|
||||
access_hash=123456789012345678,
|
||||
first_name='Lonami',
|
||||
last_name=None,
|
||||
username='Lonami',
|
||||
phone=None,
|
||||
photo=UserProfilePhoto(
|
||||
photo_id=123456789012345678,
|
||||
photo_small=FileLocation(
|
||||
dc_id=4,
|
||||
volume_id=123456789,
|
||||
local_id=123456789,
|
||||
secret=-123456789012345678
|
||||
),
|
||||
photo_big=FileLocation(
|
||||
dc_id=4,
|
||||
volume_id=123456789,
|
||||
local_id=123456789,
|
||||
secret=123456789012345678
|
||||
)
|
||||
),
|
||||
status=UserStatusOffline(
|
||||
was_online=datetime.datetime(2018, 1, 2, 3, 4, 5, tzinfo=datetime.timezone.utc)
|
||||
),
|
||||
bot_info_version=None,
|
||||
restriction_reason=None,
|
||||
bot_inline_placeholder=None,
|
||||
lang_code=None
|
||||
)
|
||||
|
||||
Now it's easy to see how we could get, for example,
|
||||
the ``was_online`` time. It's inside ``status``:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
online_at = user.status.was_online
|
||||
|
||||
You don't need to print everything to see what all the possible values
|
||||
can be. You can just search in http://lonamiwebs.github.io/Telethon/.
|
||||
|
||||
Remember that you can use Python's `isinstance
|
||||
<https://docs.python.org/3/library/functions.html#isinstance>`_
|
||||
to check the type of something. For example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import types
|
||||
|
||||
if isinstance(user.status, types.UserStatusOffline):
|
||||
print(user.status.was_online)
|
||||
|
||||
Avoiding Limits
|
||||
***************
|
||||
|
||||
Don't spam. You won't get ``FloodWaitError`` or your account banned or
|
||||
deleted if you use the library *for legit use cases*. Make cool tools.
|
||||
Don't spam! Nobody knows the exact limits for all requests since they
|
||||
depend on a lot of factors, so don't bother asking.
|
||||
|
||||
Still, if you do have a legit use case and still get those errors, the
|
||||
library will automatically sleep when they are smaller than 60 seconds
|
||||
by default. You can set different "auto-sleep" thresholds:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client.flood_sleep_threshold = 0 # Don't auto-sleep
|
||||
client.flood_sleep_threshold = 24 * 60 * 60 # Sleep always
|
||||
|
||||
You can also except it and act as you prefer:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.errors import FloodWaitError
|
||||
try:
|
||||
...
|
||||
except FloodWaitError as e:
|
||||
print('Flood waited for', e.seconds)
|
||||
quit(1)
|
||||
|
||||
VoIP numbers are very limited, and some countries are more limited too.
|
||||
|
||||
Chat or User From Messages
|
||||
**************************
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
bases. In this case, `ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>`
|
||||
knows how to get the *chat* where a thing belongs to.
|
||||
|
||||
So, a `Message <telethon.tl.custom.message.Message>` is a
|
||||
`ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>`.
|
||||
That means you can do this:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
message.is_private
|
||||
message.chat_id
|
||||
message.get_chat()
|
||||
# ...etc
|
||||
|
||||
`SenderGetter <telethon.tl.custom.sendergetter.SenderGetter>` is similar:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
message.user_id
|
||||
message.get_input_user()
|
||||
message.user
|
||||
# ...etc
|
||||
|
||||
Quite a few things implement them, so it makes sense to reuse the code.
|
||||
For example, all events (except raw updates) implement `ChatGetter
|
||||
<telethon.tl.custom.chatgetter.ChatGetter>` since all events occur
|
||||
in some chat.
|
||||
|
||||
Session Files
|
||||
*************
|
||||
|
||||
They are an important part for the library to be efficient, such as caching
|
||||
and handling your authorization key (or you would have to login every time!).
|
||||
|
||||
However, some people have a lot of trouble with SQLite, especially in Windows:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
...some lines of traceback
|
||||
'insert or replace into entities values (?,?,?,?,?)', rows)
|
||||
sqlite3.OperationalError: database is locked
|
||||
|
||||
This error occurs when **two or more clients use the same session**,
|
||||
that is, when you write the same session name to be used in the client:
|
||||
|
||||
* You have two scripts running (interactive sessions count too).
|
||||
* You have two clients in the same script running at the same time.
|
||||
|
||||
The solution is, if you need two clients, use two sessions. If the
|
||||
problem persists and you're on Linux, you can use ``fuser my.session``
|
||||
to find out the process locking the file. As a last resort, you can
|
||||
reboot your system.
|
||||
|
||||
If you really dislike SQLite, use a different session storage. There
|
||||
is an entire section covering that at :ref:`sessions`.
|
||||
|
||||
Final Words
|
||||
***********
|
||||
|
||||
Now you are aware of some common errors and use cases, this should help
|
||||
you master your Telethon skills to get the most out of the library. Have
|
||||
fun developing awesome things!
|
||||
|
|
@ -6,11 +6,8 @@ Session Files
|
|||
|
||||
.. contents::
|
||||
|
||||
They are an important part for the library to be efficient, such as caching
|
||||
and handling your authorization key (or you would have to login every time!).
|
||||
|
||||
What are Sessions?
|
||||
==================
|
||||
What are sessions?
|
||||
******************
|
||||
|
||||
The first parameter you pass to the constructor of the
|
||||
:ref:`TelegramClient <telethon-client>` is
|
||||
|
|
@ -46,14 +43,10 @@ by setting ``client.session.save_entities = False``.
|
|||
|
||||
|
||||
Different Session Storage
|
||||
=========================
|
||||
*************************
|
||||
|
||||
If you don't want to use the default SQLite session storage, you can also
|
||||
use one of the other implementations or implement your own storage.
|
||||
|
||||
While it's often not the case, it's possible that SQLite is slow enough to
|
||||
be noticeable, in which case you can also use a different storage. Note that
|
||||
this is rare and most people won't have this issue, but it's worth a mention.
|
||||
If you don't want to use the default SQLite session storage, you can also use
|
||||
one of the other implementations or implement your own storage.
|
||||
|
||||
To use a custom session storage, simply pass the custom session instance to
|
||||
:ref:`TelegramClient <telethon-client>` instead of
|
||||
|
|
@ -61,15 +54,13 @@ the session name.
|
|||
|
||||
Telethon contains three implementations of the abstract ``Session`` class:
|
||||
|
||||
.. currentmodule:: telethon.sessions
|
||||
|
||||
* `MemorySession <memory.MemorySession>`: stores session data within memory.
|
||||
* `SQLiteSession <sqlite.SQLiteSession>`: stores sessions within on-disk SQLite databases. Default.
|
||||
* `StringSession <string.StringSession>`: stores session data within memory,
|
||||
* ``MemorySession``: stores session data within memory.
|
||||
* ``SQLiteSession``: stores sessions within on-disk SQLite databases. Default.
|
||||
* ``StringSession``: stores session data within memory,
|
||||
but can be saved as a string.
|
||||
|
||||
You can import these ``from telethon.sessions``. For example, using the
|
||||
`StringSession <string.StringSession>` is done as follows:
|
||||
``StringSession`` is done as follows:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
|
|
@ -100,30 +91,25 @@ There are other community-maintained implementations available:
|
|||
* `Redis <https://github.com/ezdev128/telethon-session-redis>`_:
|
||||
stores all sessions in a single Redis data store.
|
||||
|
||||
* `MongoDB <https://github.com/watzon/telethon-session-mongo>`_:
|
||||
stores the current session in a MongoDB database.
|
||||
|
||||
|
||||
Creating your Own Storage
|
||||
=========================
|
||||
*************************
|
||||
|
||||
The easiest way to create your own storage implementation is to use
|
||||
`MemorySession <memory.MemorySession>` as the base and check out how
|
||||
`SQLiteSession <sqlite.SQLiteSession>` or one of the community-maintained
|
||||
implementations work. You can find the relevant Python files under the
|
||||
``sessions/`` directory in the Telethon's repository.
|
||||
``MemorySession`` as the base and check out how ``SQLiteSession`` or
|
||||
one of the community-maintained implementations work. You can find the
|
||||
relevant Python files under the ``sessions`` directory in Telethon.
|
||||
|
||||
After you have made your own implementation, you can add it to the
|
||||
community-maintained session implementation list above with a pull request.
|
||||
|
||||
|
||||
String Sessions
|
||||
===============
|
||||
***************
|
||||
|
||||
`StringSession <string.StringSession>` are a convenient way to embed your
|
||||
login credentials directly into your code for extremely easy portability,
|
||||
since all they take is a string to be able to login without asking for your
|
||||
phone and code (or faster start if you're using a bot token).
|
||||
``StringSession`` are a convenient way to embed your login credentials
|
||||
directly into your code for extremely easy portability, since all they
|
||||
take is a string to be able to login without asking for your phone and
|
||||
code (or faster start if you're using a bot token).
|
||||
|
||||
The easiest way to generate a string session is as follows:
|
||||
|
||||
|
|
@ -143,7 +129,7 @@ output (likely your terminal).
|
|||
.. warning::
|
||||
|
||||
**Keep this string safe!** Anyone with this string can use it
|
||||
to login into your account and do anything they want to.
|
||||
to login into your account and do anything they want to to do.
|
||||
|
||||
This is similar to leaking your ``*.session`` files online,
|
||||
but it is easier to leak a string than it is to leak a file.
|
||||
|
|
@ -157,7 +143,7 @@ you can save it in a variable directly:
|
|||
|
||||
string = '1aaNk8EX-YRfwoRsebUkugFvht6DUPi_Q25UOCzOAqzc...'
|
||||
with TelegramClient(StringSession(string), api_id, api_hash) as client:
|
||||
client.loop.run_until_complete(client.send_message('me', 'Hi'))
|
||||
client.send_message('me', 'Hi')
|
||||
|
||||
|
||||
These strings are really convenient for using in places like Heroku since
|
||||
73
readthedocs/extra/advanced-usage/update-modes.rst
Normal file
73
readthedocs/extra/advanced-usage/update-modes.rst
Normal file
|
|
@ -0,0 +1,73 @@
|
|||
.. _update-modes:
|
||||
|
||||
============
|
||||
Update Modes
|
||||
============
|
||||
|
||||
With ``asyncio``, the library has several tasks running in the background.
|
||||
One task is used for sending requests, another task is used to receive them,
|
||||
and a third one is used to handle updates.
|
||||
|
||||
To handle updates, you must keep your script running. You can do this in
|
||||
several ways. For instance, if you are *not* running ``asyncio``'s event
|
||||
loop, you should use `client.run_until_disconnected
|
||||
<telethon.client.updates.UpdateMethods.run_until_disconnected>`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import asyncio
|
||||
from telethon import TelegramClient
|
||||
|
||||
client = TelegramClient(...)
|
||||
...
|
||||
client.run_until_disconnected()
|
||||
|
||||
|
||||
Behind the scenes, this method is ``await``'ing on the `client.disconnected
|
||||
<telethon.client.telegrambaseclient.TelegramBaseClient.disconnected>` property,
|
||||
so the code above and the following are equivalent:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import asyncio
|
||||
from telethon import TelegramClient
|
||||
|
||||
client = TelegramClient(...)
|
||||
|
||||
async def main():
|
||||
await client.disconnected
|
||||
|
||||
loop = asyncio.get_event_loop()
|
||||
loop.run_until_complete(main())
|
||||
|
||||
|
||||
You could also run `client.disconnected
|
||||
<telethon.client.telegrambaseclient.TelegramBaseClient.disconnected>`
|
||||
until it completed.
|
||||
|
||||
But if you don't want to ``await``, then you should know what you want
|
||||
to be doing instead! What matters is that you shouldn't let your script
|
||||
die. If you don't care about updates, you don't need any of this.
|
||||
|
||||
Notice that unlike `client.disconnected
|
||||
<telethon.client.telegrambaseclient.TelegramBaseClient.disconnected>`,
|
||||
`client.run_until_disconnected
|
||||
<telethon.client.updates.UpdateMethods.run_until_disconnected>` will
|
||||
handle ``KeyboardInterrupt`` with you. This method is special and can
|
||||
also be ran while the loop is running, so you can do this:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
async def main():
|
||||
await client.run_until_disconnected()
|
||||
|
||||
loop.run_until_complete(main())
|
||||
|
||||
|
||||
If you need to process updates sequentially (i.e. not in parallel),
|
||||
you should set ``sequential_updates=True`` when creating the client:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
with TelegramClient(..., sequential_updates=True) as client:
|
||||
...
|
||||
|
|
@ -4,7 +4,7 @@
|
|||
Compatibility and Convenience
|
||||
=============================
|
||||
|
||||
Telethon is an `asyncio` library. Compatibility is an important concern,
|
||||
Telethon is an ``asyncio`` library. Compatibility is an important concern,
|
||||
and while it can't always be kept and mistakes happens, the :ref:`changelog`
|
||||
is there to tell you when these important changes happen.
|
||||
|
||||
|
|
@ -12,11 +12,11 @@ is there to tell you when these important changes happen.
|
|||
|
||||
|
||||
Compatibility
|
||||
=============
|
||||
*************
|
||||
|
||||
Some decisions when developing will inevitable be proven wrong in the future.
|
||||
One of these decisions was using threads. Now that Python 3.4 is reaching EOL
|
||||
and using `asyncio` is usable as of Python 3.5 it makes sense for a library
|
||||
and using ``asyncio`` is usable as of Python 3.5 it makes sense for a library
|
||||
like Telethon to make a good use of it.
|
||||
|
||||
If you have old code, **just use old versions** of the library! There is
|
||||
|
|
@ -34,7 +34,7 @@ and clean-ups. Using an older version is the right way to go.
|
|||
Sometimes, other small decisions are made. These all will be reflected in the
|
||||
:ref:`changelog` which you should read when upgrading.
|
||||
|
||||
If you want to jump the `asyncio` boat, here are some of the things you will
|
||||
If you want to jump the ``asyncio`` boat, here are some of the things you will
|
||||
need to start migrating really old code:
|
||||
|
||||
.. code-block:: python
|
||||
|
|
@ -76,7 +76,7 @@ the chat or sender. If you don't use updates, you're done!
|
|||
|
||||
|
||||
Convenience
|
||||
===========
|
||||
***********
|
||||
|
||||
.. note::
|
||||
|
||||
|
|
@ -91,7 +91,7 @@ Convenience
|
|||
This makes the examples shorter and easier to think about.
|
||||
|
||||
For quick scripts that don't need updates, it's a lot more convenient to
|
||||
forget about `asyncio` and just work with sequential code. This can prove
|
||||
forget about ``asyncio`` and just work with sequential code. This can prove
|
||||
to be a powerful hybrid for running under the Python REPL too.
|
||||
|
||||
.. code-block:: python
|
||||
|
|
@ -134,7 +134,7 @@ This keeps the best of both worlds as a sane default.
|
|||
them too. Otherwise, there is no need to do so with this mode.
|
||||
|
||||
Speed
|
||||
=====
|
||||
*****
|
||||
|
||||
When you're ready to micro-optimize your application, or if you simply
|
||||
don't need to call any non-basic methods from a synchronous context,
|
||||
|
|
@ -161,25 +161,27 @@ just get rid of ``telethon.sync`` and work inside an ``async def``:
|
|||
|
||||
await client.run_until_disconnected()
|
||||
|
||||
asyncio.run(main())
|
||||
loop = asyncio.get_event_loop()
|
||||
loop.run_until_complete(main())
|
||||
|
||||
|
||||
The ``telethon.sync`` magic module essentially wraps every method behind:
|
||||
The ``telethon.sync`` magic module simply wraps every method behind:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
asyncio.run(main())
|
||||
loop = asyncio.get_event_loop()
|
||||
loop.run_until_complete(main())
|
||||
|
||||
With some other tricks, so that you don't have to write it yourself every time.
|
||||
That's the overhead you pay if you import it, and what you save if you don't.
|
||||
So that you don't have to write it yourself every time. That's the
|
||||
overhead you pay if you import it, and what you save if you don't.
|
||||
|
||||
Learning
|
||||
========
|
||||
********
|
||||
|
||||
You know the library uses `asyncio` everywhere, and you want to learn
|
||||
how to do things right. Even though `asyncio` is its own topic, the
|
||||
You know the library uses ``asyncio`` everywhere, and you want to learn
|
||||
how to do things right. Even though ``asyncio`` is its own topic, the
|
||||
documentation wants you to learn how to use Telethon correctly, and for
|
||||
that, you need to use `asyncio` correctly too. For this reason, there
|
||||
that, you need to use ``asyncio`` correctly too. For this reason, there
|
||||
is a section called :ref:`mastering-asyncio` that will introduce you to
|
||||
the `asyncio` world, with links to more resources for learning how to
|
||||
the ``asyncio`` world, with links to more resources for learning how to
|
||||
use it. Feel free to check that section out once you have read the rest.
|
||||
263
readthedocs/extra/basic/creating-a-client.rst
Normal file
263
readthedocs/extra/basic/creating-a-client.rst
Normal file
|
|
@ -0,0 +1,263 @@
|
|||
.. _creating-a-client:
|
||||
|
||||
=================
|
||||
Creating a Client
|
||||
=================
|
||||
|
||||
|
||||
Before working with Telegram's API, you need to get your own API ID and hash:
|
||||
|
||||
1. Follow `this link <https://my.telegram.org/>`_ and login with your
|
||||
phone number.
|
||||
|
||||
2. Click under API Development tools.
|
||||
|
||||
3. A *Create new application* window will appear. Fill in your application
|
||||
details. There is no need to enter any *URL*, and only the first two
|
||||
fields (*App title* and *Short name*) can currently be changed later.
|
||||
|
||||
4. Click on *Create application* at the end. Remember that your
|
||||
**API hash is secret** and Telegram won't let you revoke it.
|
||||
Don't post it anywhere!
|
||||
|
||||
Once that's ready, the next step is to create a ``TelegramClient``.
|
||||
This class will be your main interface with Telegram's API, and creating
|
||||
one is very simple:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import TelegramClient, sync
|
||||
|
||||
# Use your own values here
|
||||
api_id = 12345
|
||||
api_hash = '0123456789abcdef0123456789abcdef'
|
||||
|
||||
client = TelegramClient('some_name', api_id, api_hash)
|
||||
|
||||
|
||||
Note that ``'some_name'`` will be used to save your session (persistent
|
||||
information such as access key and others) as ``'some_name.session'`` in
|
||||
your disk. This is by default a database file using Python's ``sqlite3``.
|
||||
|
||||
.. note::
|
||||
|
||||
It's important that the library always accesses the same session file so
|
||||
that you don't need to re-send the code over and over again. By default it
|
||||
creates the file in your working directory, but absolute paths work too.
|
||||
|
||||
|
||||
Once you have a client ready, simply `.start()
|
||||
<telethon.client.auth.AuthMethods.start>` it:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client.start()
|
||||
|
||||
This line connects to Telegram, checks whether the current user is
|
||||
authorized or not, and if it's not, it begins the login or sign up process.
|
||||
|
||||
When you're done with your code, you should always disconnect:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client = TelegramClient(...)
|
||||
try:
|
||||
client.start()
|
||||
... # your code here
|
||||
finally:
|
||||
client.disconnect()
|
||||
|
||||
|
||||
You can also use a ``with`` block to achieve the same effect:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client = TelegramClient(...)
|
||||
with client:
|
||||
... # your code here
|
||||
|
||||
# or
|
||||
with TelegramClient(...) as client:
|
||||
... # your code here
|
||||
|
||||
|
||||
Wrapping it all together:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import TelegramClient, sync
|
||||
with TelegramClient('session_name', api_id, api_hash) as client:
|
||||
... # your code
|
||||
|
||||
Just two setup lines.
|
||||
|
||||
.. warning::
|
||||
Please note that if you fail to login around 5 times (or change the first
|
||||
parameter of the :ref:`TelegramClient <telethon-client>`, which is the session
|
||||
name) you will receive a ``FloodWaitError`` of around 22 hours, so be
|
||||
careful not to mess this up! This shouldn't happen if you're doing things
|
||||
as explained, though.
|
||||
|
||||
.. note::
|
||||
If you want to use a **proxy**, you have to `install PySocks`__
|
||||
(via pip or manual) and then set the appropriated parameters:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import socks
|
||||
client = TelegramClient('session_id',
|
||||
api_id=12345, api_hash='0123456789abcdef0123456789abcdef',
|
||||
proxy=(socks.SOCKS5, 'localhost', 4444)
|
||||
)
|
||||
|
||||
The ``proxy=`` argument should be a tuple, a list or a dict,
|
||||
consisting of parameters described `here`__.
|
||||
|
||||
|
||||
Manually Signing In
|
||||
*******************
|
||||
|
||||
.. note::
|
||||
|
||||
Skip this unless you need more control when connecting.
|
||||
|
||||
If you need more control, you can replicate what `client.start()
|
||||
<telethon.client.auth.AuthMethods.start>` is doing behind the scenes
|
||||
for your convenience. The first step is to connect to the servers:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client.connect()
|
||||
|
||||
You may or may not be authorized yet. You must be authorized
|
||||
before you're able to send any request:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client.is_user_authorized() # Returns True if you can send requests
|
||||
|
||||
If you're not authorized, you need to `.sign_in
|
||||
<telethon.client.auth.AuthMethods.sign_in>`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
phone_number = '+34600000000'
|
||||
client.send_code_request(phone_number)
|
||||
myself = client.sign_in(phone_number, input('Enter code: '))
|
||||
# If .sign_in raises PhoneNumberUnoccupiedError, use .sign_up instead
|
||||
# If .sign_in raises SessionPasswordNeeded error, call .sign_in(password=...)
|
||||
# You can import both exceptions from telethon.errors.
|
||||
|
||||
.. note::
|
||||
|
||||
If you send the code that Telegram sent you over the app through the
|
||||
app itself, it will expire immediately. You can still send the code
|
||||
through the app by "obfuscating" it (maybe add a magic constant, like
|
||||
``12345``, and then subtract it to get the real code back) or any other
|
||||
technique.
|
||||
|
||||
``myself`` is your Telegram user. You can view all the information about
|
||||
yourself by doing ``print(myself.stringify())``. You're now ready to use
|
||||
the client as you wish! Remember that any object returned by the API has
|
||||
mentioned ``.stringify()`` method, and printing these might prove useful.
|
||||
|
||||
As a full example:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import TelegramClient, sync
|
||||
client = TelegramClient('session_name', api_id, api_hash)
|
||||
|
||||
client.connect()
|
||||
if not client.is_user_authorized():
|
||||
client.send_code_request(phone_number)
|
||||
me = client.sign_in(phone_number, input('Enter code: '))
|
||||
|
||||
|
||||
Remember that this is the manual process and it's so much easier
|
||||
to use the code snippets shown at the beginning of the page.
|
||||
|
||||
The code shown is just what `.start()
|
||||
<telethon.client.auth.AuthMethods.start>` will be doing behind the scenes
|
||||
(with a few extra checks), so that you know how to sign in case you want
|
||||
to avoid using ``input()`` (the default) for whatever reason. If no phone
|
||||
or bot token is provided, you will be asked one through ``input()``. The
|
||||
method also accepts a ``phone=`` and ``bot_token`` parameters.
|
||||
|
||||
You can use either, as both will work. Determining which
|
||||
is just a matter of taste, and how much control you need.
|
||||
|
||||
Remember that you can get yourself at any time with `client.get_me()
|
||||
<telethon.client.users.UserMethods.get_me>`.
|
||||
|
||||
|
||||
Two Factor Authorization (2FA)
|
||||
------------------------------
|
||||
|
||||
If you have Two Factor Authorization (from now on, 2FA) enabled on your
|
||||
account, calling `.sign_in()
|
||||
<telethon.client.auth.AuthMethods.sign_in>` will raise a
|
||||
``SessionPasswordNeededError``. When this happens, just use the method
|
||||
again with a ``password=``:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import getpass
|
||||
from telethon.errors import SessionPasswordNeededError
|
||||
|
||||
client.sign_in(phone)
|
||||
try:
|
||||
client.sign_in(code=input('Enter code: '))
|
||||
except SessionPasswordNeededError:
|
||||
client.sign_in(password=getpass.getpass())
|
||||
|
||||
|
||||
The mentioned `.start()
|
||||
<telethon.client.auth.AuthMethods.start>` method will handle this for you as
|
||||
well, but you must set the ``password=`` parameter beforehand (it won't be
|
||||
asked).
|
||||
|
||||
If you don't have 2FA enabled, but you would like to do so through the
|
||||
library, use `client.edit_2fa()
|
||||
<telethon.client.auth.AuthMethods.edit_2fa>`.
|
||||
|
||||
Be sure to know what you're doing when using this function and
|
||||
you won't run into any problems. Take note that if you want to
|
||||
set only the email/hint and leave the current password unchanged,
|
||||
you need to "redo" the 2fa.
|
||||
|
||||
See the examples below:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.errors import EmailUnconfirmedError
|
||||
|
||||
# Sets 2FA password for first time:
|
||||
client.edit_2fa(new_password='supersecurepassword')
|
||||
|
||||
# Changes password:
|
||||
client.edit_2fa(current_password='supersecurepassword',
|
||||
new_password='changedmymind')
|
||||
|
||||
# Clears current password (i.e. removes 2FA):
|
||||
client.edit_2fa(current_password='changedmymind', new_password=None)
|
||||
|
||||
# Sets new password with recovery email:
|
||||
try:
|
||||
client.edit_2fa(new_password='memes and dreams',
|
||||
email='JohnSmith@example.com')
|
||||
# Raises error (you need to check your email to complete 2FA setup.)
|
||||
except EmailUnconfirmedError:
|
||||
# You can put email checking code here if desired.
|
||||
pass
|
||||
|
||||
# Also take note that unless you remove 2FA or explicitly
|
||||
# give email parameter again it will keep the last used setting
|
||||
|
||||
# Set hint after already setting password:
|
||||
client.edit_2fa(current_password='memes and dreams',
|
||||
new_password='memes and dreams',
|
||||
hint='It keeps you alive')
|
||||
|
||||
__ https://github.com/Anorov/PySocks#installation
|
||||
__ https://github.com/Anorov/PySocks#usage-1
|
||||
213
readthedocs/extra/basic/entities.rst
Normal file
213
readthedocs/extra/basic/entities.rst
Normal file
|
|
@ -0,0 +1,213 @@
|
|||
.. _entities:
|
||||
|
||||
=========================
|
||||
Users, Chats and Channels
|
||||
=========================
|
||||
|
||||
|
||||
.. important::
|
||||
|
||||
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
|
||||
applications"? Now do the same with the library. Use what applies:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
with client:
|
||||
# Does it have an username? Use it!
|
||||
entity = client.get_entity(username)
|
||||
|
||||
# Do you have a conversation open with them? Get dialogs.
|
||||
client.get_dialogs()
|
||||
|
||||
# Are they participant of some group? Get them.
|
||||
client.get_participants('TelethonChat')
|
||||
|
||||
# Is the entity the original sender of a forwarded message? Get it.
|
||||
client.get_messages('TelethonChat', 100)
|
||||
|
||||
# NOW you can use the ID, anywhere!
|
||||
entity = client.get_entity(123456)
|
||||
client.send_message(123456, 'Hi!')
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. contents::
|
||||
|
||||
|
||||
Introduction
|
||||
************
|
||||
|
||||
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`.
|
||||
|
||||
.. 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 contacts.
|
||||
|
||||
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
|
||||
`client.get_dialogs() <telethon.client.dialogs.DialogMethods.get_dialogs>`.
|
||||
If the peer is someone in a group, you would similarly
|
||||
`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.
|
||||
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.
|
||||
|
||||
|
||||
Getting entities
|
||||
****************
|
||||
|
||||
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:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Dialogs are the "conversations you have open".
|
||||
# This method returns a list of Dialog, which
|
||||
# has the .entity attribute and other information.
|
||||
dialogs = client.get_dialogs()
|
||||
|
||||
# All of these work and do the same.
|
||||
lonami = client.get_entity('lonami')
|
||||
lonami = client.get_entity('t.me/lonami')
|
||||
lonami = client.get_entity('https://telegram.dog/lonami')
|
||||
|
||||
# Other kind of entities.
|
||||
channel = client.get_entity('telegram.me/joinchat/AAAAAEkk2WdoDrB4-Q8-gg')
|
||||
contact = client.get_entity('+34xxxxxxxxx')
|
||||
friend = client.get_entity(friend_id)
|
||||
|
||||
# Getting entities through their ID (User, Chat or Channel)
|
||||
entity = 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 = client.get_entity(PeerUser(some_id))
|
||||
my_chat = client.get_entity(PeerChat(some_id))
|
||||
my_channel = client.get_entity(PeerChannel(some_id))
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
You **don't** need to get the entity before using it! Just let
|
||||
the library do its job. Use the phone, username, ID or input
|
||||
entity (preferred but not necessary), whatever you already have.
|
||||
|
||||
All methods in the :ref:`telegram-client` call `.get_input_entity()
|
||||
<telethon.client.users.UserMethods.get_input_entity>` prior
|
||||
to sending the requst to save you from the hassle of doing so manually.
|
||||
That way, convenience calls such as `client.send_message('lonami', '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::
|
||||
|
||||
Don't worry if you don't understand this section, just remember some
|
||||
of the details listed here are important. When you're calling a method,
|
||||
don't call `client.get_entity() <telethon.client.users.UserMethods.get_entity>`
|
||||
beforehand, just use the username or phone, or the entity retrieved by
|
||||
other means like `client.get_dialogs()
|
||||
<telethon.client.dialogs.DialogMethods.get_dialogs>`.
|
||||
|
||||
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 use 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
|
||||
|
||||
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.
|
||||
95
readthedocs/extra/basic/getting-started.rst
Normal file
95
readthedocs/extra/basic/getting-started.rst
Normal file
|
|
@ -0,0 +1,95 @@
|
|||
.. _getting-started:
|
||||
|
||||
|
||||
===============
|
||||
Getting Started
|
||||
===============
|
||||
|
||||
.. contents::
|
||||
|
||||
|
||||
Simple Installation
|
||||
*******************
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
pip3 install telethon
|
||||
|
||||
**More details**: :ref:`installation`
|
||||
|
||||
|
||||
Creating a client
|
||||
*****************
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import TelegramClient, sync
|
||||
|
||||
# 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'
|
||||
|
||||
client = TelegramClient('session_name', api_id, api_hash).start()
|
||||
|
||||
**More details**: :ref:`creating-a-client`
|
||||
|
||||
|
||||
Basic Usage
|
||||
***********
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Getting information about yourself
|
||||
me = client.get_me()
|
||||
print(me.stringify())
|
||||
|
||||
# Sending a message (you can use 'me' or 'self' to message yourself)
|
||||
client.send_message('username', 'Hello World from Telethon!')
|
||||
|
||||
# Sending a file
|
||||
client.send_file('username', '/home/myself/Pictures/holidays.jpg')
|
||||
|
||||
# Retrieving messages from a chat
|
||||
from telethon import utils
|
||||
for message in client.iter_messages('username', limit=10):
|
||||
print(utils.get_display_name(message.sender), message.message)
|
||||
|
||||
# Listing all the dialogs (conversations you have open)
|
||||
for dialog in client.get_dialogs(limit=10):
|
||||
print(dialog.name, dialog.draft.text)
|
||||
|
||||
# Downloading profile photos (default path is the working directory)
|
||||
client.download_profile_photo('username')
|
||||
|
||||
# Once you have a message with .media (if message.media)
|
||||
# you can download it using client.download_media(),
|
||||
# or even using message.download_media():
|
||||
messages = client.get_messages('username')
|
||||
messages[0].download_media()
|
||||
|
||||
**More details**: :ref:`telegram-client`
|
||||
|
||||
See :ref:`telethon-client` for all available friendly methods.
|
||||
|
||||
|
||||
Handling Updates
|
||||
****************
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import events
|
||||
|
||||
@client.on(events.NewMessage(incoming=True, pattern='(?i)hi'))
|
||||
async def handler(event):
|
||||
await event.reply('Hello!')
|
||||
|
||||
client.run_until_disconnected()
|
||||
|
||||
**More details**: :ref:`working-with-updates`
|
||||
|
||||
|
||||
----------
|
||||
|
||||
You can continue by clicking on the "More details" link below each
|
||||
snippet of code or the "Next" button at the bottom of the page.
|
||||
99
readthedocs/extra/basic/installation.rst
Normal file
99
readthedocs/extra/basic/installation.rst
Normal file
|
|
@ -0,0 +1,99 @@
|
|||
.. _installation:
|
||||
|
||||
============
|
||||
Installation
|
||||
============
|
||||
|
||||
.. contents::
|
||||
|
||||
|
||||
Automatic Installation
|
||||
**********************
|
||||
|
||||
To install Telethon, simply do:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
pip3 install telethon
|
||||
|
||||
Needless to say, you must have Python 3 and PyPi installed in your system.
|
||||
See https://python.org and https://pypi.python.org/pypi/pip for more.
|
||||
|
||||
If you already have the library installed, upgrade with:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
pip3 install --upgrade telethon
|
||||
|
||||
You can also install the library directly from GitHub or a fork:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
# pip3 install git+https://github.com/LonamiWebs/Telethon.git
|
||||
or
|
||||
$ git clone https://github.com/LonamiWebs/Telethon.git
|
||||
$ cd Telethon/
|
||||
# pip install -Ue .
|
||||
|
||||
If you don't have root access, simply pass the ``--user`` flag to the pip
|
||||
command. If you want to install a specific branch, append ``@branch`` to
|
||||
the end of the first install command.
|
||||
|
||||
By default the library will use a pure Python implementation for encryption,
|
||||
which can be really slow when uploading or downloading files. If you don't
|
||||
mind using a C extension, install `cryptg <https://github.com/Lonami/cryptg>`__
|
||||
via ``pip`` or as an extra:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
pip3 install telethon[cryptg]
|
||||
|
||||
|
||||
Manual Installation
|
||||
*******************
|
||||
|
||||
1. Install the required ``pyaes`` (`GitHub`__ | `PyPi`__) and
|
||||
``rsa`` (`GitHub`__ | `PyPi`__) modules:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
pip3 install pyaes rsa
|
||||
|
||||
2. Clone Telethon's GitHub repository:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
git clone https://github.com/LonamiWebs/Telethon.git
|
||||
|
||||
3. Enter the cloned repository:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
cd Telethon
|
||||
|
||||
4. Run the code generator:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
python3 setup.py gen
|
||||
|
||||
5. Done!
|
||||
|
||||
To generate the `method documentation`__, ``python3 setup.py gen docs``.
|
||||
|
||||
|
||||
Optional dependencies
|
||||
*********************
|
||||
|
||||
If the `cryptg`__ is installed, you might notice a speed-up in the download
|
||||
and upload speed, since these are the most cryptographic-heavy part of the
|
||||
library and said module is a C extension. Otherwise, the ``pyaes`` fallback
|
||||
will be used.
|
||||
|
||||
|
||||
__ https://github.com/ricmoo/pyaes
|
||||
__ https://pypi.python.org/pypi/pyaes
|
||||
__ https://github.com/sybrenstuvel/python-rsa
|
||||
__ https://pypi.python.org/pypi/rsa/3.4.2
|
||||
__ https://lonamiwebs.github.io/Telethon
|
||||
__ https://github.com/Lonami/cryptg
|
||||
104
readthedocs/extra/basic/telegram-client.rst
Normal file
104
readthedocs/extra/basic/telegram-client.rst
Normal file
|
|
@ -0,0 +1,104 @@
|
|||
.. _telegram-client:
|
||||
|
||||
==============
|
||||
TelegramClient
|
||||
==============
|
||||
|
||||
.. note::
|
||||
|
||||
Make sure to use the friendly methods described in :ref:`telethon-client`!
|
||||
This section is just an introduction to using the client, but all the
|
||||
available methods are in the :ref:`telethon-client` reference, including
|
||||
detailed descriptions to what they do.
|
||||
|
||||
The :ref:`TelegramClient <telethon-client>` is the
|
||||
central class of the library, the one you will be using most of the time. For
|
||||
this reason, it's important to know what it offers.
|
||||
|
||||
Since we're working with Python, one must not forget that we can do
|
||||
``help(client)`` or ``help(TelegramClient)`` at any time for a more
|
||||
detailed description and a list of all the available methods. Calling
|
||||
``help()`` from an interactive Python session will always list all the
|
||||
methods for any object, even yours!
|
||||
|
||||
Interacting with the Telegram API is done through sending **requests**,
|
||||
this is, any "method" listed on the API. There are a few methods (and
|
||||
growing!) on the :ref:`TelegramClient <telethon-client>` class that abstract
|
||||
you from the need of manually importing the requests you need.
|
||||
|
||||
For instance, retrieving your own user can be done in a single line
|
||||
(assuming you have ``from telethon import sync`` or ``import telethon.sync``):
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
myself = client.get_me()
|
||||
|
||||
Internally, this method has sent a request to Telegram, who replied with
|
||||
the information about your own user, and then the desired information
|
||||
was extracted from their response.
|
||||
|
||||
If you want to retrieve any other user, chat or channel (channels are a
|
||||
special subset of chats), you want to retrieve their "entity". This is
|
||||
how the library refers to either of these:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# The method will infer that you've passed a username
|
||||
# It also accepts phone numbers, and will get the user
|
||||
# from your contact list.
|
||||
lonami = client.get_entity('lonami')
|
||||
|
||||
The so called "entities" are another important whole concept on its own,
|
||||
but for now you don't need to worry about it. Simply know that they are
|
||||
a good way to get information about a user, chat or channel.
|
||||
|
||||
Many other common methods for quick scripts are also available:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Note that you can use 'me' or 'self' to message yourself
|
||||
client.send_message('username', 'Hello World from Telethon!')
|
||||
|
||||
# .send_message's parse mode defaults to markdown, so you
|
||||
# can use **bold**, __italics__, [links](https://example.com), `code`,
|
||||
# and even [mentions](@username)/[mentions](tg://user?id=123456789)
|
||||
client.send_message('username', '**Using** __markdown__ `too`!')
|
||||
|
||||
client.send_file('username', '/home/myself/Pictures/holidays.jpg')
|
||||
|
||||
# The utils package has some goodies, like .get_display_name()
|
||||
from telethon import utils
|
||||
for message in client.iter_messages('username', limit=10):
|
||||
print(utils.get_display_name(message.sender), message.message)
|
||||
|
||||
# Dialogs are the conversations you have open
|
||||
for dialog in client.get_dialogs(limit=10):
|
||||
print(dialog.name, dialog.draft.text)
|
||||
|
||||
# Default path is the working directory
|
||||
client.download_profile_photo('username')
|
||||
|
||||
# Call .disconnect() when you're done
|
||||
client.disconnect()
|
||||
|
||||
Remember that you can call ``.stringify()`` to any object Telegram returns
|
||||
to pretty print it. Calling ``str(result)`` does the same operation, but on
|
||||
a single line.
|
||||
|
||||
|
||||
Available methods
|
||||
*****************
|
||||
|
||||
The :ref:`reference <telethon-package>` lists all the "handy" methods
|
||||
available for you to use in the :ref:`TelegramClient <telethon-client>` class.
|
||||
These are simply wrappers around the "raw" Telegram API, making it much more
|
||||
manageable and easier to work with.
|
||||
|
||||
Please refer to :ref:`accessing-the-full-api` if these aren't enough,
|
||||
and don't be afraid to read the source code of the InteractiveTelegramClient_
|
||||
or even the TelegramClient_ itself to learn how it works.
|
||||
|
||||
See the mentioned :ref:`telethon-client` to find the available methods.
|
||||
|
||||
.. _InteractiveTelegramClient: https://github.com/LonamiWebs/Telethon/blob/master/telethon_examples/interactive_telegram_client.py
|
||||
.. _TelegramClient: https://github.com/LonamiWebs/Telethon/tree/master/telethon/client
|
||||
333
readthedocs/extra/basic/working-with-updates.rst
Normal file
333
readthedocs/extra/basic/working-with-updates.rst
Normal file
|
|
@ -0,0 +1,333 @@
|
|||
.. _working-with-updates:
|
||||
|
||||
====================
|
||||
Working with Updates
|
||||
====================
|
||||
|
||||
.. important::
|
||||
|
||||
Coming from Telethon before it reached its version 1.0?
|
||||
Make sure to read :ref:`compatibility-and-convenience`!
|
||||
Otherwise, you can ignore this note and just follow along.
|
||||
|
||||
The library comes with the `telethon.events` module. *Events* are an abstraction
|
||||
over what Telegram calls `updates`__, and are meant to ease simple and common
|
||||
usage when dealing with them, since there are many updates. If you're looking
|
||||
for the method reference, check :ref:`telethon-events-package`, otherwise,
|
||||
let's dive in!
|
||||
|
||||
|
||||
.. important::
|
||||
|
||||
The library logs by default no output, and any exception that occurs
|
||||
inside your handlers will be "hidden" from you to prevent the thread
|
||||
from terminating (so it can still deliver events). You should enable
|
||||
logging when working with events, at least the error level, to see if
|
||||
this is happening so you can debug the error.
|
||||
|
||||
**When using updates, please enable logging:**
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import logging
|
||||
logging.basicConfig(level=logging.ERROR)
|
||||
|
||||
|
||||
.. contents::
|
||||
|
||||
|
||||
Getting Started
|
||||
***************
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import TelegramClient, events
|
||||
|
||||
client = TelegramClient('name', api_id, api_hash)
|
||||
|
||||
@client.on(events.NewMessage)
|
||||
async def my_event_handler(event):
|
||||
if 'hello' in event.raw_text:
|
||||
await event.reply('hi!')
|
||||
|
||||
client.start()
|
||||
client.run_until_disconnected()
|
||||
|
||||
|
||||
Not much, but there might be some things unclear. What does this code do?
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import TelegramClient, events
|
||||
|
||||
client = TelegramClient('name', api_id, api_hash)
|
||||
|
||||
|
||||
This is normal creation (of course, pass session name, API ID and hash).
|
||||
Nothing we don't know already.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@client.on(events.NewMessage)
|
||||
|
||||
|
||||
This Python decorator will attach itself to the ``my_event_handler``
|
||||
definition, and basically means that *on* a `NewMessage
|
||||
<telethon.events.newmessage.NewMessage>` *event*,
|
||||
the callback function you're about to define will be called:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
async def my_event_handler(event):
|
||||
if 'hello' in event.raw_text:
|
||||
await event.reply('hi!')
|
||||
|
||||
|
||||
If a `NewMessage
|
||||
<telethon.events.newmessage.NewMessage>` event occurs,
|
||||
and ``'hello'`` is in the text of the message, we `.reply()
|
||||
<telethon.tl.custom.message.Message.reply>` to the event
|
||||
with a ``'hi!'`` message.
|
||||
|
||||
Do you notice anything different? Yes! Event handlers **must** be ``async``
|
||||
for them to work, and **every method using the network** needs to have an
|
||||
``await``, otherwise, Python's ``asyncio`` will tell you that you forgot
|
||||
to do so, so you can easily add it.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client.start()
|
||||
client.run_until_disconnected()
|
||||
|
||||
|
||||
Finally, this tells the client that we're done with our code. We run the
|
||||
``asyncio`` loop until the client starts (this is done behind the scenes,
|
||||
since the method is so common), and then we run it again until we are
|
||||
disconnected. Of course, you can do other things instead of running
|
||||
until disconnected. For this refer to :ref:`update-modes`.
|
||||
|
||||
|
||||
More on events
|
||||
**************
|
||||
|
||||
The `NewMessage <telethon.events.newmessage.NewMessage>` event has much
|
||||
more than what was shown. You can access the `.sender
|
||||
<telethon.tl.custom.message.Message.sender>` of the message
|
||||
through that member, or even see if the message had `.media
|
||||
<telethon.tl.custom.message.Message.media>`, a `.photo
|
||||
<telethon.tl.custom.message.Message.photo>` or a `.document
|
||||
<telethon.tl.custom.message.Message.document>` (which you
|
||||
could download with for example `client.download_media(event.photo)
|
||||
<telethon.client.downloads.DownloadMethods.download_media>`.
|
||||
|
||||
If you don't want to `.reply()
|
||||
<telethon.tl.custom.message.Message.reply>` as a reply,
|
||||
you can use the `.respond() <telethon.tl.custom.message.Message.respond>`
|
||||
method instead. Of course, there are more events such as `ChatAction
|
||||
<telethon.events.chataction.ChatAction>` or `UserUpdate
|
||||
<telethon.events.userupdate.UserUpdate>`, and they're all
|
||||
used in the same way. Simply add the `@client.on(events.XYZ)
|
||||
<telethon.client.updates.UpdateMethods.on>` decorator on the top
|
||||
of your handler and you're done! The event that will be passed always
|
||||
is of type ``XYZ.Event`` (for instance, `NewMessage.Event
|
||||
<telethon.events.newmessage.NewMessage.Event>`), except for the `Raw
|
||||
<telethon.events.raw.Raw>` event which just passes the :tl:`Update` object.
|
||||
|
||||
Note that `.reply()
|
||||
<telethon.tl.custom.message.Message.reply>` and `.respond()
|
||||
<telethon.tl.custom.message.Message.respond>` are just wrappers around the
|
||||
`client.send_message() <telethon.client.messages.MessageMethods.send_message>`
|
||||
method which supports the ``file=`` parameter.
|
||||
This means you can reply with a photo if you do `event.reply(file=photo)
|
||||
<telethon.tl.custom.message.Message.reply>`.
|
||||
|
||||
You can put the same event on many handlers, and even different events on
|
||||
the same handler. You can also have a handler work on only specific chats,
|
||||
for example:
|
||||
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import ast
|
||||
import random
|
||||
|
||||
|
||||
# Either a single item or a list of them will work for the chats.
|
||||
# You can also use the IDs, Peers, or even User/Chat/Channel objects.
|
||||
@client.on(events.NewMessage(chats=('TelethonChat', 'TelethonOffTopic')))
|
||||
async def normal_handler(event):
|
||||
if 'roll' in event.raw_text:
|
||||
await event.reply(str(random.randint(1, 6)))
|
||||
|
||||
|
||||
# Similarly, you can use incoming=True for messages that you receive
|
||||
@client.on(events.NewMessage(chats='TelethonOffTopic', outgoing=True,
|
||||
pattern='eval (.+)'))
|
||||
async def admin_handler(event):
|
||||
expression = event.pattern_match.group(1)
|
||||
await event.reply(str(ast.literal_eval(expression)))
|
||||
|
||||
|
||||
You can pass one or more chats to the ``chats`` parameter (as a list or tuple),
|
||||
and only events from there will be processed. You can also specify whether you
|
||||
want to handle incoming or outgoing messages (those you receive or those you
|
||||
send). In this example, people can say ``'roll'`` and you will reply with a
|
||||
random number, while if you say ``'eval 4+4'``, you will reply with the
|
||||
solution. Try it!
|
||||
|
||||
|
||||
Properties vs. Methods
|
||||
**********************
|
||||
|
||||
The event shown above acts just like a `custom.Message
|
||||
<telethon.tl.custom.message.Message>`, which means you
|
||||
can access all the properties it has, like ``.sender``.
|
||||
|
||||
**However** events are different to other methods in the client, like
|
||||
`client.get_messages <telethon.client.messages.MessageMethods.get_messages>`.
|
||||
Events *may not* send information about the sender or chat, which means it
|
||||
can be ``None``, but all the methods defined in the client always have this
|
||||
information so it doesn't need to be re-fetched. For this reason, you have
|
||||
``get_`` methods, which will make a network call if necessary.
|
||||
|
||||
In short, you should do this:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@client.on(events.NewMessage)
|
||||
async def handler(event):
|
||||
# event.input_chat may be None, use event.get_input_chat()
|
||||
chat = await event.get_input_chat()
|
||||
sender = await event.get_sender()
|
||||
buttons = await event.get_buttons()
|
||||
|
||||
async def main():
|
||||
async for message in client.iter_messages('me', 10):
|
||||
# Methods from the client always have these properties ready
|
||||
chat = message.input_chat
|
||||
sender = message.sender
|
||||
buttons = message.buttons
|
||||
|
||||
Notice, properties (`message.sender
|
||||
<telethon.tl.custom.message.Message.sender>`) don't need an ``await``, but
|
||||
methods (`message.get_sender
|
||||
<telethon.tl.custom.message.Message.get_sender>`) **do** need an ``await``,
|
||||
and you should use methods in events for these properties that may need network.
|
||||
|
||||
|
||||
Events Without the client
|
||||
*************************
|
||||
|
||||
The code of your application starts getting big, so you decide to
|
||||
separate the handlers into different files. But how can you access
|
||||
the client from these files? You don't need to! Just `events.register
|
||||
<telethon.events.register>` them:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# handlers/welcome.py
|
||||
from telethon import events
|
||||
|
||||
@events.register(events.NewMessage('(?i)hello'))
|
||||
async def handler(event):
|
||||
client = event.client
|
||||
await event.respond('Hey!')
|
||||
await client.send_message('me', 'I said hello to someone')
|
||||
|
||||
|
||||
Registering events is a way of saying "this method is an event handler".
|
||||
You can use `telethon.events.is_handler` to check if any method is a handler.
|
||||
You can think of them as a different approach to Flask's blueprints.
|
||||
|
||||
It's important to note that this does **not** add the handler to any client!
|
||||
You never specified the client on which the handler should be used. You only
|
||||
declared that it is a handler, and its type.
|
||||
|
||||
To actually use the handler, you need to `client.add_event_handler
|
||||
<telethon.client.updates.UpdateMethods.add_event_handler>` to the
|
||||
client (or clients) where they should be added to:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# main.py
|
||||
from telethon import TelegramClient
|
||||
import handlers.welcome
|
||||
|
||||
with TelegramClient(...) as client:
|
||||
client.add_event_handler(handlers.welcome.handler)
|
||||
client.run_until_disconnected()
|
||||
|
||||
|
||||
This also means that you can register an event handler once and
|
||||
then add it to many clients without re-declaring the event.
|
||||
|
||||
|
||||
Events Without Decorators
|
||||
*************************
|
||||
|
||||
If for any reason you don't want to use `telethon.events.register`,
|
||||
you can explicitly pass the event handler to use to the mentioned
|
||||
`client.add_event_handler
|
||||
<telethon.client.updates.UpdateMethods.add_event_handler>`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import TelegramClient, events
|
||||
|
||||
async def handler(event):
|
||||
...
|
||||
|
||||
with TelegramClient(...) as client:
|
||||
client.add_event_handler(handler, events.NewMessage)
|
||||
client.run_until_disconnected()
|
||||
|
||||
|
||||
Similarly, you also have `client.remove_event_handler
|
||||
<telethon.client.updates.UpdateMethods.remove_event_handler>`
|
||||
and `client.list_event_handlers
|
||||
<telethon.client.updates.UpdateMethods.list_event_handlers>`.
|
||||
|
||||
The ``event`` argument is optional in all three methods and defaults to
|
||||
`events.Raw <telethon.events.raw.Raw>` for adding, and ``None`` when
|
||||
removing (so all callbacks would be removed).
|
||||
|
||||
.. note::
|
||||
|
||||
The ``event`` type is ignored in `client.add_event_handler
|
||||
<telethon.client.updates.UpdateMethods.add_event_handler>`
|
||||
if you have used `telethon.events.register` on the ``callback``
|
||||
before, since that's the point of using such method at all.
|
||||
|
||||
|
||||
Stopping Propagation of Updates
|
||||
*******************************
|
||||
|
||||
There might be cases when an event handler is supposed to be used solitary and
|
||||
it makes no sense to process any other handlers in the chain. For this case,
|
||||
it is possible to raise a `telethon.events.StopPropagation` exception which
|
||||
will cause the propagation of the update through your handlers to stop:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.events import StopPropagation
|
||||
|
||||
@client.on(events.NewMessage)
|
||||
async def _(event):
|
||||
# ... some conditions
|
||||
await event.delete()
|
||||
|
||||
# Other handlers won't have an event to work with
|
||||
raise StopPropagation
|
||||
|
||||
@client.on(events.NewMessage)
|
||||
async def _(event):
|
||||
# Will never be reached, because it is the second handler
|
||||
# in the chain.
|
||||
pass
|
||||
|
||||
|
||||
Remember to check :ref:`telethon-events-package` if you're looking for
|
||||
the methods reference.
|
||||
|
||||
|
||||
__ https://lonamiwebs.github.io/Telethon/types/update.html
|
||||
File diff suppressed because it is too large
Load Diff
54
readthedocs/extra/developing/api-status.rst
Normal file
54
readthedocs/extra/developing/api-status.rst
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
.. _api-status:
|
||||
|
||||
==========
|
||||
API Status
|
||||
==========
|
||||
|
||||
|
||||
In an attempt to help everyone who works with the Telegram API, the
|
||||
library will by default report all *Remote Procedure Call* errors to
|
||||
`RPC PWRTelegram <https://rpc.pwrtelegram.xyz/>`__, a public database
|
||||
anyone can query, made by `Daniil <https://github.com/danog>`__. All the
|
||||
information sent is a ``GET`` request with the error code, error message
|
||||
and method used.
|
||||
|
||||
If you still would like to opt out, you can disable this feature by setting
|
||||
``client.session.report_errors = False``. However Daniil would really thank
|
||||
you if you helped him (and everyone) by keeping it on!
|
||||
|
||||
Querying the API status
|
||||
***********************
|
||||
|
||||
The API is accessed through ``GET`` requests, which can be made for
|
||||
instance through ``curl``. A JSON response will be returned.
|
||||
|
||||
**All known errors and their description**:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
curl https://rpc.pwrtelegram.xyz/?all
|
||||
|
||||
**Error codes for a specific request**:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
curl https://rpc.pwrtelegram.xyz/?for=messages.sendMessage
|
||||
|
||||
**Number of** ``RPC_CALL_FAIL``:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
curl https://rpc.pwrtelegram.xyz/?rip # last hour
|
||||
curl https://rpc.pwrtelegram.xyz/?rip=$(time()-60) # last minute
|
||||
|
||||
**Description of errors**:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
curl https://rpc.pwrtelegram.xyz/?description_for=SESSION_REVOKED
|
||||
|
||||
**Code of a specific error**:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
curl https://rpc.pwrtelegram.xyz/?code_for=STICKERSET_INVALID
|
||||
|
|
@ -4,7 +4,7 @@ Project Structure
|
|||
|
||||
|
||||
Main interface
|
||||
==============
|
||||
**************
|
||||
|
||||
The library itself is under the ``telethon/`` directory. The
|
||||
``__init__.py`` file there exposes the main ``TelegramClient``, a class
|
||||
|
|
@ -33,8 +33,13 @@ The sender makes use of a ``Connection`` class which knows the format in
|
|||
which outgoing messages should be sent (how to encode their length and
|
||||
their body, if they're further encrypted).
|
||||
|
||||
For now, all connection modes make use of the ``extensions/tcpclient``,
|
||||
a C#-like ``TcpClient`` to ease working with sockets in Python. All the
|
||||
``TcpClient`` know is how to connect through TCP and writing/reading
|
||||
from the socket with optional cancel.
|
||||
|
||||
Auto-generated code
|
||||
===================
|
||||
*******************
|
||||
|
||||
The files under ``telethon_generator/`` are used to generate the code
|
||||
that gets placed under ``telethon/tl/``. The parsers take in files in
|
||||
|
|
@ -45,7 +50,3 @@ an index so that they can be imported easily.
|
|||
|
||||
Custom documentation can also be generated to easily navigate through
|
||||
the vast amount of items offered by the API.
|
||||
|
||||
If you clone the repository, you will have to run ``python setup.py gen``
|
||||
in order to generate the code. Installing the library runs the generator
|
||||
too, but the mentioned command will just generate code.
|
||||
|
|
@ -0,0 +1,73 @@
|
|||
===============================
|
||||
Telegram API in Other Languages
|
||||
===============================
|
||||
|
||||
|
||||
Telethon was made for **Python**, and as far as I know, there is no
|
||||
*exact* port to other languages. However, there *are* other
|
||||
implementations made by awesome people (one needs to be awesome to
|
||||
understand the official Telegram documentation) on several languages
|
||||
(even more Python too), listed below:
|
||||
|
||||
C
|
||||
*
|
||||
|
||||
Possibly the most well-known unofficial open source implementation out
|
||||
there by `@vysheng <https://github.com/vysheng>`__,
|
||||
`tgl <https://github.com/vysheng/tgl>`__, and its console client
|
||||
`telegram-cli <https://github.com/vysheng/tg>`__. Latest development
|
||||
has been moved to `BitBucket <https://bitbucket.org/vysheng/tdcli>`__.
|
||||
|
||||
C++
|
||||
***
|
||||
|
||||
The newest (and official) library, written from scratch, is called
|
||||
`tdlib <https://github.com/tdlib/td>`__ and is what the Telegram X
|
||||
uses. You can find more information in the official documentation,
|
||||
published `here <https://core.telegram.org/tdlib/docs/>`__.
|
||||
|
||||
JavaScript
|
||||
**********
|
||||
|
||||
`@zerobias <https://github.com/zerobias>`__ is working on
|
||||
`telegram-mtproto <https://github.com/zerobias/telegram-mtproto>`__,
|
||||
a work-in-progress JavaScript library installable via
|
||||
`npm <https://www.npmjs.com/>`__.
|
||||
|
||||
Kotlin
|
||||
******
|
||||
|
||||
`Kotlogram <https://github.com/badoualy/kotlogram>`__ is a Telegram
|
||||
implementation written in Kotlin (one of the
|
||||
`official <https://blog.jetbrains.com/kotlin/2017/05/kotlin-on-android-now-official/>`__
|
||||
languages for
|
||||
`Android <https://developer.android.com/kotlin/index.html>`__) by
|
||||
`@badoualy <https://github.com/badoualy>`__, currently as a beta–
|
||||
yet working.
|
||||
|
||||
PHP
|
||||
***
|
||||
|
||||
A PHP implementation is also available thanks to
|
||||
`@danog <https://github.com/danog>`__ and his
|
||||
`MadelineProto <https://github.com/danog/MadelineProto>`__ project, with
|
||||
a very nice `online
|
||||
documentation <https://daniil.it/MadelineProto/API_docs/>`__ too.
|
||||
|
||||
Python
|
||||
******
|
||||
|
||||
A fairly new (as of the end of 2017) Telegram library written from the
|
||||
ground up in Python by
|
||||
`@delivrance <https://github.com/delivrance>`__ and his
|
||||
`Pyrogram <https://github.com/pyrogram/pyrogram>`__ library.
|
||||
There isn't really a reason to pick it over Telethon and it'd be kinda
|
||||
sad to see you go, but it would be nice to know what you miss from each
|
||||
other library in either one so both can improve.
|
||||
|
||||
Rust
|
||||
****
|
||||
|
||||
Yet another work-in-progress implementation, this time for Rust thanks
|
||||
to `@JuanPotato <https://github.com/JuanPotato>`__ under the fancy
|
||||
name of `Vail <https://github.com/JuanPotato/Vail>`__.
|
||||
|
|
@ -12,7 +12,7 @@ To run Telethon on a test server, use the following code:
|
|||
|
||||
You can check your ``'test ip'`` on https://my.telegram.org.
|
||||
|
||||
You should set `None` session so to ensure you're generating a new
|
||||
You should set ``None`` session so to ensure you're generating a new
|
||||
authorization key for it (it would fail if you used a session where you
|
||||
had previously connected to another data center).
|
||||
|
||||
|
|
@ -35,7 +35,3 @@ times, in this case, ``22222`` so we can hardcode that:
|
|||
client.start(
|
||||
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.
|
||||
73
readthedocs/extra/examples/bots.rst
Normal file
73
readthedocs/extra/examples/bots.rst
Normal file
|
|
@ -0,0 +1,73 @@
|
|||
====
|
||||
Bots
|
||||
====
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
These examples assume you have read :ref:`accessing-the-full-api`.
|
||||
|
||||
.. contents::
|
||||
|
||||
|
||||
Talking to Inline Bots
|
||||
**********************
|
||||
|
||||
You can query an inline bot, such as `@VoteBot`__ (note, *query*,
|
||||
not *interact* with a voting message), by making use of the
|
||||
:tl:`GetInlineBotResultsRequest` request:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.tl.functions.messages import GetInlineBotResultsRequest
|
||||
|
||||
bot_results = client(GetInlineBotResultsRequest(
|
||||
bot, user_or_chat, 'query', ''
|
||||
))
|
||||
|
||||
And you can select any of their results by using
|
||||
:tl:`SendInlineBotResultRequest`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.tl.functions.messages import SendInlineBotResultRequest
|
||||
|
||||
client(SendInlineBotResultRequest(
|
||||
get_input_peer(user_or_chat),
|
||||
obtained_query_id,
|
||||
obtained_str_id
|
||||
))
|
||||
|
||||
|
||||
Talking to Bots with special reply markup
|
||||
*****************************************
|
||||
|
||||
Generally, you just use the `message.click()
|
||||
<telethon.tl.custom.message.Message.click>` method:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
messages = client.get_messages('somebot')
|
||||
messages[0].click(0)
|
||||
|
||||
You can also do it manually.
|
||||
|
||||
To interact with a message that has a special reply markup, such as
|
||||
`@VoteBot`__ polls, you would use :tl:`GetBotCallbackAnswerRequest`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.tl.functions.messages import GetBotCallbackAnswerRequest
|
||||
|
||||
client(GetBotCallbackAnswerRequest(
|
||||
user_or_chat,
|
||||
msg.id,
|
||||
data=msg.reply_markup.rows[wanted_row].buttons[wanted_button].data
|
||||
))
|
||||
|
||||
It's a bit verbose, but it has all the information you would need to
|
||||
show it visually (button rows, and buttons within each row, each with
|
||||
its own data).
|
||||
|
||||
__ https://t.me/vote
|
||||
__ https://t.me/vote
|
||||
327
readthedocs/extra/examples/chats-and-channels.rst
Normal file
327
readthedocs/extra/examples/chats-and-channels.rst
Normal file
|
|
@ -0,0 +1,327 @@
|
|||
===============================
|
||||
Working with Chats and Channels
|
||||
===============================
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
These examples assume you have read :ref:`accessing-the-full-api`.
|
||||
|
||||
.. contents::
|
||||
|
||||
|
||||
Joining a chat or channel
|
||||
*************************
|
||||
|
||||
Note that :tl:`Chat` are normal groups, and :tl:`Channel` are a
|
||||
special form of :tl:`Chat`, which can also be super-groups if
|
||||
their ``megagroup`` member is ``True``.
|
||||
|
||||
|
||||
Joining a public channel
|
||||
************************
|
||||
|
||||
Once you have the :ref:`entity <entities>` of the channel you want to join
|
||||
to, you can make use of the :tl:`JoinChannelRequest` to join such channel:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.tl.functions.channels import JoinChannelRequest
|
||||
client(JoinChannelRequest(channel))
|
||||
|
||||
# In the same way, you can also leave such channel
|
||||
from telethon.tl.functions.channels import LeaveChannelRequest
|
||||
client(LeaveChannelRequest(input_channel))
|
||||
|
||||
|
||||
For more on channels, check the `channels namespace`__.
|
||||
|
||||
|
||||
__ https://lonamiwebs.github.io/Telethon/methods/channels/index.html
|
||||
|
||||
|
||||
Joining a private chat or channel
|
||||
*********************************
|
||||
|
||||
If all you have is a link like this one:
|
||||
``https://t.me/joinchat/AAAAAFFszQPyPEZ7wgxLtd``, you already have
|
||||
enough information to join! The part after the
|
||||
``https://t.me/joinchat/``, this is, ``AAAAAFFszQPyPEZ7wgxLtd`` on this
|
||||
example, is the ``hash`` of the chat or channel. Now you can use
|
||||
:tl:`ImportChatInviteRequest` as follows:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.tl.functions.messages import ImportChatInviteRequest
|
||||
updates = client(ImportChatInviteRequest('AAAAAEHbEkejzxUjAUCfYg'))
|
||||
|
||||
|
||||
Adding someone else to such chat or channel
|
||||
*******************************************
|
||||
|
||||
If you don't want to add yourself, maybe because you're already in,
|
||||
you can always add someone else with the :tl:`AddChatUserRequest`, which
|
||||
use is very straightforward, or :tl:`InviteToChannelRequest` for channels:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# For normal chats
|
||||
from telethon.tl.functions.messages import AddChatUserRequest
|
||||
|
||||
# Note that ``user_to_add`` is NOT the name of the parameter.
|
||||
# It's the user you want to add (``user_id=user_to_add``).
|
||||
client(AddChatUserRequest(
|
||||
chat_id,
|
||||
user_to_add,
|
||||
fwd_limit=10 # Allow the user to see the 10 last messages
|
||||
))
|
||||
|
||||
# For channels (which includes megagroups)
|
||||
from telethon.tl.functions.channels import InviteToChannelRequest
|
||||
|
||||
client(InviteToChannelRequest(
|
||||
channel,
|
||||
[users_to_add]
|
||||
))
|
||||
|
||||
|
||||
Checking a link without joining
|
||||
*******************************
|
||||
|
||||
If you don't need to join but rather check whether it's a group or a
|
||||
channel, you can use the :tl:`CheckChatInviteRequest`, which takes in
|
||||
the hash of said channel or group.
|
||||
|
||||
|
||||
Retrieving all chat members (channels too)
|
||||
******************************************
|
||||
|
||||
.. note::
|
||||
|
||||
Use the `telethon.telegram_client.TelegramClient.iter_participants`
|
||||
friendly method instead unless you have a better reason not to!
|
||||
|
||||
This method will handle different chat types for you automatically.
|
||||
|
||||
|
||||
Here is the easy way to do it:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
participants = client.get_participants(group)
|
||||
|
||||
Now we will show how the method works internally.
|
||||
|
||||
In order to get all the members from a mega-group or channel, you need
|
||||
to use :tl:`GetParticipantsRequest`. As we can see it needs an
|
||||
:tl:`InputChannel`, (passing the mega-group or channel you're going to
|
||||
use will work), and a mandatory :tl:`ChannelParticipantsFilter`. The
|
||||
closest thing to "no filter" is to simply use
|
||||
:tl:`ChannelParticipantsSearch` with an empty ``'q'`` string.
|
||||
|
||||
If we want to get *all* the members, we need to use a moving offset and
|
||||
a fixed limit:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.tl.functions.channels import GetParticipantsRequest
|
||||
from telethon.tl.types import ChannelParticipantsSearch
|
||||
from time import sleep
|
||||
|
||||
offset = 0
|
||||
limit = 100
|
||||
all_participants = []
|
||||
|
||||
while True:
|
||||
participants = client(GetParticipantsRequest(
|
||||
channel, ChannelParticipantsSearch(''), offset, limit, hash=0
|
||||
))
|
||||
if not participants.users:
|
||||
break
|
||||
all_participants.extend(participants.users)
|
||||
offset += len(participants.users)
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
If you need more than 10,000 members from a group you should use the
|
||||
mentioned ``client.get_participants(..., aggressive=True)``. It will
|
||||
do some tricks behind the scenes to get as many entities as possible.
|
||||
Refer to `issue 573`__ for more on this.
|
||||
|
||||
|
||||
Note that :tl:`GetParticipantsRequest` returns :tl:`ChannelParticipants`,
|
||||
which may have more information you need (like the role of the
|
||||
participants, total count of members, etc.)
|
||||
|
||||
__ https://github.com/LonamiWebs/Telethon/issues/573
|
||||
|
||||
|
||||
Recent Actions
|
||||
**************
|
||||
|
||||
"Recent actions" is simply the name official applications have given to
|
||||
the "admin log". Simply use :tl:`GetAdminLogRequest` for that, and
|
||||
you'll get AdminLogResults.events in return which in turn has the final
|
||||
`.action`__.
|
||||
|
||||
__ https://lonamiwebs.github.io/Telethon/types/channel_admin_log_event_action.html
|
||||
|
||||
|
||||
Admin Permissions
|
||||
*****************
|
||||
|
||||
Giving or revoking admin permissions can be done with the :tl:`EditAdminRequest`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.tl.functions.channels import EditAdminRequest
|
||||
from telethon.tl.types import ChannelAdminRights
|
||||
|
||||
# You need both the channel and who to grant permissions
|
||||
# They can either be channel/user or input channel/input user.
|
||||
#
|
||||
# ChannelAdminRights is a list of granted permissions.
|
||||
# Set to True those you want to give.
|
||||
rights = ChannelAdminRights(
|
||||
post_messages=None,
|
||||
add_admins=None,
|
||||
invite_users=None,
|
||||
change_info=True,
|
||||
ban_users=None,
|
||||
delete_messages=True,
|
||||
pin_messages=True,
|
||||
invite_link=None,
|
||||
edit_messages=None
|
||||
)
|
||||
# Equivalent to:
|
||||
# rights = ChannelAdminRights(
|
||||
# change_info=True,
|
||||
# delete_messages=True,
|
||||
# pin_messages=True
|
||||
# )
|
||||
|
||||
# Once you have a ChannelAdminRights, invoke it
|
||||
client(EditAdminRequest(channel, user, rights))
|
||||
|
||||
# User will now be able to change group info, delete other people's
|
||||
# messages and pin messages.
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
Thanks to `@Kyle2142`__ for `pointing out`__ that you **cannot** set all
|
||||
parameters to ``True`` to give a user full permissions, as not all
|
||||
permissions are related to both broadcast channels/megagroups.
|
||||
|
||||
E.g. trying to set ``post_messages=True`` in a megagroup will raise an
|
||||
error. It is recommended to always use keyword arguments, and to set only
|
||||
the permissions the user needs. If you don't need to change a permission,
|
||||
it can be omitted (full list `here`__).
|
||||
|
||||
|
||||
Restricting Users
|
||||
*****************
|
||||
|
||||
Similar to how you give or revoke admin permissions, you can edit the
|
||||
banned rights of a user through :tl:`EditBannedRequest` and its parameter
|
||||
:tl:`ChannelBannedRights`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.tl.functions.channels import EditBannedRequest
|
||||
from telethon.tl.types import ChannelBannedRights
|
||||
|
||||
from datetime import datetime, timedelta
|
||||
|
||||
# Restricting a user for 7 days, only allowing view/send messages.
|
||||
#
|
||||
# Note that it's "reversed". You must set to ``True`` the permissions
|
||||
# you want to REMOVE, and leave as ``None`` those you want to KEEP.
|
||||
rights = ChannelBannedRights(
|
||||
until_date=timedelta(days=7),
|
||||
view_messages=None,
|
||||
send_messages=None,
|
||||
send_media=True,
|
||||
send_stickers=True,
|
||||
send_gifs=True,
|
||||
send_games=True,
|
||||
send_inline=True,
|
||||
embed_links=True
|
||||
)
|
||||
|
||||
# The above is equivalent to
|
||||
rights = ChannelBannedRights(
|
||||
until_date=datetime.now() + timedelta(days=7),
|
||||
send_media=True,
|
||||
send_stickers=True,
|
||||
send_gifs=True,
|
||||
send_games=True,
|
||||
send_inline=True,
|
||||
embed_links=True
|
||||
)
|
||||
|
||||
client(EditBannedRequest(channel, user, rights))
|
||||
|
||||
|
||||
You can also use a ``datetime`` object for ``until_date=``, or even a
|
||||
Unix timestamp. Note that if you ban someone for less than 30 seconds
|
||||
or for more than 366 days, Telegram will consider the ban to actually
|
||||
last forever. This is officially documented under
|
||||
https://core.telegram.org/bots/api#restrictchatmember.
|
||||
|
||||
|
||||
Kicking a member
|
||||
****************
|
||||
|
||||
Telegram doesn't actually have a request to kick a user from a group.
|
||||
Instead, you need to restrict them so they can't see messages. Any date
|
||||
is enough:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.tl.functions.channels import EditBannedRequest
|
||||
from telethon.tl.types import ChannelBannedRights
|
||||
|
||||
client(EditBannedRequest(
|
||||
channel, user, ChannelBannedRights(
|
||||
until_date=None,
|
||||
view_messages=True
|
||||
)
|
||||
))
|
||||
|
||||
|
||||
__ https://github.com/Kyle2142
|
||||
__ https://github.com/LonamiWebs/Telethon/issues/490
|
||||
__ https://lonamiwebs.github.io/Telethon/constructors/channel_admin_rights.html
|
||||
|
||||
|
||||
Increasing View Count in a Channel
|
||||
**********************************
|
||||
|
||||
It has been asked `quite`__ `a few`__ `times`__ (really, `many`__), and
|
||||
while I don't understand why so many people ask this, the solution is to
|
||||
use :tl:`GetMessagesViewsRequest`, setting ``increment=True``:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
|
||||
# Obtain `channel' through dialogs or through client.get_entity() or anyhow.
|
||||
# Obtain `msg_ids' through `.get_messages()` or anyhow. Must be a list.
|
||||
|
||||
client(GetMessagesViewsRequest(
|
||||
peer=channel,
|
||||
id=msg_ids,
|
||||
increment=True
|
||||
))
|
||||
|
||||
|
||||
Note that you can only do this **once or twice a day** per account,
|
||||
running this in a loop will obviously not increase the views forever
|
||||
unless you wait a day between each iteration. If you run it any sooner
|
||||
than that, the views simply won't be increased.
|
||||
|
||||
__ https://github.com/LonamiWebs/Telethon/issues/233
|
||||
__ https://github.com/LonamiWebs/Telethon/issues/305
|
||||
__ https://github.com/LonamiWebs/Telethon/issues/409
|
||||
__ https://github.com/LonamiWebs/Telethon/issues/447
|
||||
55
readthedocs/extra/examples/projects-using-telethon.rst
Normal file
55
readthedocs/extra/examples/projects-using-telethon.rst
Normal file
|
|
@ -0,0 +1,55 @@
|
|||
=======================
|
||||
Projects using Telethon
|
||||
=======================
|
||||
|
||||
This page lists some real world examples showcasing what can be built with
|
||||
the library.
|
||||
|
||||
.. note::
|
||||
|
||||
Do you have a project that uses the library or know of any that's not
|
||||
listed here? Feel free to leave a comment at
|
||||
`issue 744 <https://github.com/LonamiWebs/Telethon/issues/744>`_
|
||||
so it can be included in the next revision of the documentation!
|
||||
|
||||
.. _projects-telegram-export:
|
||||
|
||||
telethon_examples/
|
||||
******************
|
||||
|
||||
`Link <https://github.com/LonamiWebs/Telethon/tree/master/telethon_examples>`_ /
|
||||
`Author's website <https://lonamiwebs.github.io>`_
|
||||
|
||||
This documentation is not the only place where you can find useful code
|
||||
snippets using the library. The main repository also has a folder with
|
||||
some cool examples (even a Tkinter GUI!) which you can download, edit
|
||||
and run to learn and play with them.
|
||||
|
||||
telegram-export
|
||||
***************
|
||||
|
||||
`Link <https://github.com/expectocode/telegram-export>`_ /
|
||||
`Author's website <https://github.com/expectocode>`_
|
||||
|
||||
A tool to download Telegram data (users, chats, messages, and media)
|
||||
into a database (and display the saved data).
|
||||
|
||||
.. _projects-mautrix-telegram:
|
||||
|
||||
mautrix-telegram
|
||||
****************
|
||||
|
||||
`Link <https://github.com/tulir/mautrix-telegram>`_ /
|
||||
`Author's website <https://maunium.net/>`_
|
||||
|
||||
A Matrix-Telegram hybrid puppeting/relaybot bridge.
|
||||
|
||||
.. _projects-telegramtui:
|
||||
|
||||
TelegramTUI
|
||||
***********
|
||||
|
||||
`Link <https://github.com/bad-day/TelegramTUI>`_ /
|
||||
`Author's website <https://github.com/bad-day>`_
|
||||
|
||||
A Telegram client on your terminal.
|
||||
645
readthedocs/extra/examples/telegram-client.rst
Normal file
645
readthedocs/extra/examples/telegram-client.rst
Normal file
|
|
@ -0,0 +1,645 @@
|
|||
.. _telegram-client-example:
|
||||
|
||||
|
||||
========================
|
||||
Examples with the Client
|
||||
========================
|
||||
|
||||
This section explores the methods defined in the :ref:`telegram-client`
|
||||
with some practical examples. The section assumes that you have imported
|
||||
the ``telethon.sync`` package and that you have a client ready to use.
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
There are some very common errors (such as forgetting to add
|
||||
``import telethon.sync``) for newcomers to ``asyncio``:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# AttributeError: 'coroutine' object has no attribute 'first_name'
|
||||
print(client.get_me().first_name)
|
||||
|
||||
# TypeError: 'AsyncGenerator' object is not iterable
|
||||
for message in client.iter_messages('me'):
|
||||
...
|
||||
|
||||
# RuntimeError: This event loop is already running
|
||||
with client.conversation('me') as conv:
|
||||
...
|
||||
|
||||
That error means you're probably inside an ``async def`` so you
|
||||
need to use:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
print((await client.get_me()).first_name)
|
||||
async for message in client.iter_messages('me'):
|
||||
...
|
||||
|
||||
async with client.conversation('me') as conv:
|
||||
...
|
||||
|
||||
You can of course call other ``def`` functions from your ``async def``
|
||||
event handlers, but if they need making API calls, make your own
|
||||
functions ``async def`` so you can ``await`` things:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
async def helper(client):
|
||||
await client.send_message('me', 'Hi')
|
||||
|
||||
If you're not inside an ``async def`` you can enter one like so:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import asyncio
|
||||
loop = asyncio.get_event_loop()
|
||||
loop.run_until_complete(my_async_def())
|
||||
|
||||
|
||||
.. contents::
|
||||
|
||||
|
||||
Authorization
|
||||
*************
|
||||
|
||||
Starting the client is as easy as calling `client.start()
|
||||
<telethon.client.auth.AuthMethods.start>`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client.start()
|
||||
... # code using the client
|
||||
client.disconnect()
|
||||
|
||||
And you can even use a ``with`` block:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
with client:
|
||||
... # code using the client
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
Remember we assume you have ``import telethon.sync``. You can of course
|
||||
use the library without importing it. The code would be rewritten as:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import asyncio
|
||||
loop = asyncio.get_event_loop()
|
||||
|
||||
async def main():
|
||||
await client.start()
|
||||
...
|
||||
await client.disconnect()
|
||||
|
||||
# or
|
||||
async with client:
|
||||
...
|
||||
|
||||
loop.run_until_complete(main())
|
||||
|
||||
All methods that need access to the network (e.g. to make an API call)
|
||||
**must** be awaited (or their equivalent such as ``async for`` and
|
||||
``async with``). You can do this yourself or you can let the library
|
||||
do it for you by using ``import telethon.sync``. With event handlers,
|
||||
you must do this yourself.
|
||||
|
||||
The cleanest way to delete your ``*.session`` file is `client.log_out
|
||||
<telethon.client.auth.AuthMethods.log_out>`. Note that you will obviously
|
||||
need to login again if you use this:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Logs out and deletes the session file; you will need to sign in again
|
||||
client.log_out()
|
||||
|
||||
# You often simply want to disconnect. You will not need to sign in again
|
||||
client.disconnect()
|
||||
|
||||
|
||||
Group Chats
|
||||
***********
|
||||
|
||||
You can easily iterate over all the :tl:`User` in a chat and
|
||||
do anything you want with them by using `client.iter_participants
|
||||
<telethon.client.chats.ChatMethods.iter_participants>`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
for user in client.iter_participants(chat):
|
||||
... # do something with the user
|
||||
|
||||
You can also search by their name:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
for user in client.iter_participants(chat, search='name'):
|
||||
...
|
||||
|
||||
Or by their type (e.g. if they are admin) with :tl:`ChannelParticipantsFilter`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.tl.types import ChannelParticipantsAdmins
|
||||
|
||||
for user in client.iter_participants(chat, filter=ChannelParticipantsAdmins):
|
||||
...
|
||||
|
||||
|
||||
Open Conversations and Joined Channels
|
||||
**************************************
|
||||
|
||||
The conversations you have open and the channels you have joined
|
||||
are in your "dialogs", so to get them you need to `client.get_dialogs
|
||||
<telethon.client.dialogs.DialogMethods.get_dialogs>`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
dialogs = client.get_dialogs()
|
||||
first = dialogs[0]
|
||||
print(first.title)
|
||||
|
||||
You can then use the dialog as if it were a peer:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client.send_message(first, 'hi')
|
||||
|
||||
|
||||
You can access `dialog.draft <telethon.tl.custom.draft.Draft>` or you can
|
||||
get them all at once without getting the dialogs:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
drafts = client.get_drafts()
|
||||
|
||||
|
||||
Downloading Media
|
||||
*****************
|
||||
|
||||
It's easy to `download_profile_photo
|
||||
<telethon.client.downloads.DownloadMethods.download_profile_photo>`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client.download_profile_photo(user)
|
||||
|
||||
Or `download_media <telethon.client.downloads.DownloadMethods.download_media>`
|
||||
from a message:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client.download_media(message)
|
||||
client.download_media(message, filename)
|
||||
# or
|
||||
message.download_media()
|
||||
message.download_media(filename)
|
||||
|
||||
Remember that these methods return the final filename where the
|
||||
media was downloaded (e.g. it may add the extension automatically).
|
||||
|
||||
Getting Messages
|
||||
****************
|
||||
|
||||
You can easily iterate over all the `messages
|
||||
<telethon.tl.custom.message.Message>` of a chat with `iter_messages
|
||||
<telethon.client.messages.MessageMethods.iter_messages>`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
for message in client.iter_messages(chat):
|
||||
... # do something with the message from recent to older
|
||||
|
||||
for message in client.iter_messages(chat, reverse=True):
|
||||
... # going from the oldest to the most recent
|
||||
|
||||
You can also use it to search for messages from a specific person:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
for message in client.iter_messages(chat, from_user='me'):
|
||||
...
|
||||
|
||||
Or you can search by text:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
for message in client.iter_messages(chat, search='hello'):
|
||||
...
|
||||
|
||||
Or you can search by media with a :tl:`MessagesFilter`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.tl.types import InputMessagesFilterPhotos
|
||||
|
||||
for message in client.iter_messages(chat, filter=InputMessagesFilterPhotos):
|
||||
...
|
||||
|
||||
If you want a list instead, use the get variant. The second
|
||||
argument is the limit, and ``None`` means "get them all":
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
|
||||
from telethon.tl.types import InputMessagesFilterPhotos
|
||||
|
||||
# Get 0 photos and print the total
|
||||
photos = client.get_messages(chat, 0, filter=InputMessagesFilterPhotos)
|
||||
print(photos.total)
|
||||
|
||||
# Get all the photos
|
||||
photos = client.get_messages(chat, None, filter=InputMessagesFilterPhotos)
|
||||
|
||||
Or just some IDs:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
message_1337 = client.get_messages(chats, ids=1337)
|
||||
|
||||
|
||||
Sending Messages
|
||||
****************
|
||||
|
||||
Just use `send_message <telethon.client.messages.MessageMethods.send_message>`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client.send_message('lonami', 'Thanks for the Telethon library!')
|
||||
|
||||
The function returns the `custom.Message <telethon.tl.custom.message.Message>`
|
||||
that was sent so you can do more things with it if you want.
|
||||
|
||||
You can also `reply <telethon.tl.custom.message.Message.reply>` or
|
||||
`respond <telethon.tl.custom.message.Message.respond>` to messages:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
message.reply('Hello')
|
||||
message.respond('World')
|
||||
|
||||
Sending Markdown or HTML messages
|
||||
*********************************
|
||||
|
||||
Markdown (``'md'`` or ``'markdown'``) is the default `parse_mode
|
||||
<telethon.client.messageparse.MessageParseMethods.parse_mode>`
|
||||
for the client. You can change the default parse mode like so:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client.parse_mode = 'html'
|
||||
|
||||
|
||||
Now all messages will be formatted as HTML by default:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client.send_message('me', 'Some <b>bold</b> and <i>italic</i> text')
|
||||
client.send_message('me', 'An <a href="https://example.com">URL</a>')
|
||||
client.send_message('me', '<code>code</code> and <pre>pre\nblocks</pre>')
|
||||
client.send_message('me', '<a href="tg://user?id=me">Mentions</a>')
|
||||
|
||||
|
||||
You can override the default parse mode to use for special cases:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# No parse mode by default
|
||||
client.parse_mode = None
|
||||
|
||||
# ...but here I want markdown
|
||||
client.send_message('me', 'Hello, **world**!', parse_mode='md')
|
||||
|
||||
# ...and here I need HTML
|
||||
client.send_message('me', 'Hello, <i>world</i>!', parse_mode='html')
|
||||
|
||||
The rules are the same as for Bot API, so please refer to
|
||||
https://core.telegram.org/bots/api#formatting-options.
|
||||
|
||||
Sending Messages with Media
|
||||
***************************
|
||||
|
||||
Sending media can be done with `send_file
|
||||
<telethon.client.uploads.UploadMethods.send_file>`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client.send_file(chat, '/my/photos/me.jpg', caption="It's me!")
|
||||
# or
|
||||
client.send_message(chat, "It's me!", file='/my/photos/me.jpg')
|
||||
|
||||
You can send voice notes or round videos by setting the right arguments:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client.send_file(chat, '/my/songs/song.mp3', voice_note=True)
|
||||
client.send_file(chat, '/my/videos/video.mp4', video_note=True)
|
||||
|
||||
You can set a JPG thumbnail for any document:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client.send_file(chat, '/my/documents/doc.txt', thumb='photo.jpg')
|
||||
|
||||
You can force sending images as documents:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client.send_file(chat, '/my/photos/photo.png', force_document=True)
|
||||
|
||||
You can send albums if you pass more than one file:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client.send_file(chat, [
|
||||
'/my/photos/holiday1.jpg',
|
||||
'/my/photos/holiday2.jpg',
|
||||
'/my/drawings/portrait.png'
|
||||
])
|
||||
|
||||
The caption can also be a list to match the different photos.
|
||||
|
||||
Sending Messages with Buttons
|
||||
*****************************
|
||||
|
||||
You must sign in as a bot in order to add inline buttons (or normal
|
||||
keyboards) to your messages. Once you have signed in as a bot specify
|
||||
the `Button <telethon.tl.custom.button.Button>` or buttons to use:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.tl.custom import Button
|
||||
|
||||
async def callback(event):
|
||||
await event.edit('Thank you!')
|
||||
|
||||
client.send_message(chat, 'Hello!',
|
||||
buttons=Button.inline('Click me', callback))
|
||||
|
||||
|
||||
You can also add the event handler yourself, or change the data payload:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import events
|
||||
|
||||
@client.on(events.CallbackQuery)
|
||||
async def handler(event):
|
||||
await event.answer('You clicked {}!'.format(event.data))
|
||||
|
||||
client.send_message(chat, 'Pick one', buttons=[
|
||||
[Button.inline('Left'), Button.inline('Right')],
|
||||
[Button.url('Check my site!', 'https://lonamiwebs.github.io')]
|
||||
])
|
||||
|
||||
You can also use normal buttons (not inline) to request the user's
|
||||
location, phone number, or simply for them to easily send a message:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client.send_message(chat, 'Welcome', buttons=[
|
||||
Button.text('Thanks!'),
|
||||
Button.request_phone('Send phone'),
|
||||
Button.request_location('Send location')
|
||||
])
|
||||
|
||||
Forcing a reply or removing the keyboard can also be done:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client.send_message(chat, 'Reply to me', buttons=Button.force_reply())
|
||||
client.send_message(chat, 'Bye Keyboard!', buttons=Button.clear())
|
||||
|
||||
Remember to check `Button <telethon.tl.custom.button.Button>` for more.
|
||||
|
||||
Making Inline Queries
|
||||
*********************
|
||||
|
||||
You can send messages ``via @bot`` by first making an inline query:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
results = client.inline_query('like', 'Do you like Telethon?')
|
||||
|
||||
Then access the result you want and `click
|
||||
<telethon.tl.custom.inlineresult.InlineResult.click>` it in the chat
|
||||
where you want to send it to:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
message = results[0].click('TelethonOffTopic')
|
||||
|
||||
Sending messages through inline bots lets you use buttons as a normal user.
|
||||
|
||||
It can look a bit strange at first, but you can make inline queries in no
|
||||
chat in particular, and then click a *result* to send it to some chat.
|
||||
|
||||
Clicking Buttons
|
||||
****************
|
||||
|
||||
Let's `click <telethon.tl.custom.message.Message.click>`
|
||||
the message we sent in the example above!
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
message.click(0)
|
||||
|
||||
This will click the first button in the message. You could also
|
||||
``click(row, column)``, using some text such as ``click(text='👍')``
|
||||
or even the data directly ``click(data=b'payload')``.
|
||||
|
||||
Answering Inline Queries
|
||||
************************
|
||||
|
||||
As a bot, you can answer to inline queries with `events.InlineQuery
|
||||
<telethon.events.inlinequery.InlineQuery>`. You should make use of the
|
||||
`builder <telethon.tl.custom.inlinebuilder.InlineBuilder>` property
|
||||
to conveniently build the list of results to show to the user. Remember
|
||||
to check the properties of the `InlineQuery.Event
|
||||
<telethon.events.inlinequery.InlineQuery.Event>`:
|
||||
|
||||
.. 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')
|
||||
])
|
||||
|
||||
Conversations: Waiting for Messages or Replies
|
||||
**********************************************
|
||||
|
||||
This one is really useful for unit testing your bots, which you can
|
||||
even write within Telethon itself! You can open a `Conversation
|
||||
<telethon.tl.custom.conversation.Conversation>` in any chat as:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
with client.conversation(chat) as conv:
|
||||
...
|
||||
|
||||
Conversations let you program a finite state machine with the
|
||||
higher-level constructs we are all used to, such as ``while``
|
||||
and ``if`` conditionals instead setting the state and jumping
|
||||
from one place to another which is less clean.
|
||||
|
||||
For instance, let's imagine ``you`` are the bot talking to ``usr``:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
<you> Hi!
|
||||
<usr> Hello!
|
||||
<you> Please tell me your name
|
||||
<usr> ?
|
||||
<you> Your name didn't have any letters! Try again
|
||||
<usr> Lonami
|
||||
<you> Thanks Lonami!
|
||||
|
||||
This can be programmed as follows:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
with bot.conversation(chat) as conv:
|
||||
conv.send_message('Hi!')
|
||||
hello = conv.get_response()
|
||||
|
||||
conv.send_message('Please tell me your name')
|
||||
name = conv.get_response().raw_text
|
||||
while not any(x.isalpha() for x in name):
|
||||
conv.send_message("Your name didn't have any letters! Try again")
|
||||
name = conv.get_response().raw_text
|
||||
|
||||
conv.send_message('Thanks {}!'.format(name))
|
||||
|
||||
Note how we sent a message **with the conversation**, not with the client.
|
||||
This is important so the conversation remembers what messages you sent.
|
||||
|
||||
The method reference for getting a response, getting a reply or marking
|
||||
the conversation as read can be found by clicking here: `Conversation
|
||||
<telethon.tl.custom.conversation.Conversation>`.
|
||||
|
||||
Sending a message or getting a response returns a `Message
|
||||
<telethon.tl.custom.message.Message>`. Reading its documentation
|
||||
will also be really useful!
|
||||
|
||||
If a reply never arrives or too many messages come in, getting
|
||||
responses will raise ``asyncio.TimeoutError`` or ``ValueError``
|
||||
respectively. You may want to ``except`` these and tell the user
|
||||
they were too slow, or simply drop the conversation.
|
||||
|
||||
|
||||
Forwarding Messages
|
||||
*******************
|
||||
|
||||
You can forward up to 100 messages with `forward_messages
|
||||
<telethon.client.messages.MessageMethods.forward_messages>`,
|
||||
or a single one if you have the message with `forward_to
|
||||
<telethon.tl.custom.message.Message.forward_to>`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# a single one
|
||||
client.forward_messages(chat, message)
|
||||
# or
|
||||
client.forward_messages(chat, message_id, from_chat)
|
||||
# or
|
||||
message.forward_to(chat)
|
||||
|
||||
# multiple
|
||||
client.forward_messages(chat, messages)
|
||||
# or
|
||||
client.forward_messages(chat, message_ids, from_chat)
|
||||
|
||||
You can also "forward" messages without showing "Forwarded from" by
|
||||
re-sending the message:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client.send_message(chat, message)
|
||||
|
||||
|
||||
Editing Messages
|
||||
****************
|
||||
|
||||
With `edit_message <telethon.client.messages.MessageMethods.edit_message>`
|
||||
or `message.edit <telethon.tl.custom.message.Message.edit>`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client.edit_message(message, 'New text')
|
||||
# or
|
||||
message.edit('New text')
|
||||
# or
|
||||
client.edit_message(chat, message_id, 'New text')
|
||||
|
||||
Deleting Messages
|
||||
*****************
|
||||
|
||||
With `delete_messages <telethon.client.messages.MessageMethods.delete_messages>`
|
||||
or `message.delete <telethon.tl.custom.message.Message.delete>`. Note that the
|
||||
first one supports deleting entire chats at once!:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client.delete_messages(chat, messages)
|
||||
# or
|
||||
message.delete()
|
||||
|
||||
|
||||
Marking Messages as Read
|
||||
************************
|
||||
|
||||
Marking messages up to a certain point as read with `send_read_acknowledge
|
||||
<telethon.client.messages.MessageMethods.send_read_acknowledge>`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
client.send_read_acknowledge(last_message)
|
||||
# or
|
||||
client.send_read_acknowledge(last_message_id)
|
||||
# or
|
||||
client.send_read_acknowledge(messages)
|
||||
|
||||
|
||||
Getting Entities
|
||||
****************
|
||||
|
||||
Entities are users, chats, or channels. You can get them by their ID if
|
||||
you have seen them before (e.g. you probably need to get all dialogs or
|
||||
all the members from a chat first):
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import utils
|
||||
|
||||
me = client.get_entity('me')
|
||||
print(utils.get_display_name(me))
|
||||
|
||||
chat = client.get_input_entity('username')
|
||||
for message in client.iter_messages(chat):
|
||||
...
|
||||
|
||||
# Note that you could have used the username directly, but it's
|
||||
# good to use get_input_entity if you will reuse it a lot.
|
||||
for message in client.iter_messages('username'):
|
||||
...
|
||||
|
||||
some_id = client.get_peer_id('+34123456789')
|
||||
|
||||
The documentation for shown methods are `get_entity
|
||||
<telethon.client.users.UserMethods.get_entity>`, `get_input_entity
|
||||
<telethon.client.users.UserMethods.get_input_entity>` and `get_peer_id
|
||||
<telethon.client.users.UserMethods.get_peer_id>`.
|
||||
|
||||
Note that the utils package also has a `get_peer_id
|
||||
<telethon.utils.get_peer_id>` but it won't work with things
|
||||
that need access to the network such as usernames or phones,
|
||||
which need to be in your contact list.
|
||||
|
|
@ -5,13 +5,13 @@ Users
|
|||
|
||||
.. note::
|
||||
|
||||
These examples assume you have read :ref:`full-api`.
|
||||
These examples assume you have read :ref:`accessing-the-full-api`.
|
||||
|
||||
.. contents::
|
||||
|
||||
|
||||
Retrieving full information
|
||||
===========================
|
||||
***************************
|
||||
|
||||
If you need to retrieve the bio, biography or about information for a user
|
||||
you should use :tl:`GetFullUser`:
|
||||
|
|
@ -21,18 +21,18 @@ you should use :tl:`GetFullUser`:
|
|||
|
||||
from telethon.tl.functions.users import GetFullUserRequest
|
||||
|
||||
full = await client(GetFullUserRequest(user))
|
||||
full = client(GetFullUserRequest(user))
|
||||
# or even
|
||||
full = await client(GetFullUserRequest('username'))
|
||||
full = client(GetFullUserRequest('username'))
|
||||
|
||||
bio = full.full_user.about
|
||||
bio = full.about
|
||||
|
||||
|
||||
See :tl:`UserFull` to know what other fields you can access.
|
||||
|
||||
|
||||
Updating your name and/or bio
|
||||
=============================
|
||||
*****************************
|
||||
|
||||
The first name, last name and bio (about) can all be changed with the same
|
||||
request. Omitted fields won't change after invoking :tl:`UpdateProfile`:
|
||||
|
|
@ -41,13 +41,13 @@ request. Omitted fields won't change after invoking :tl:`UpdateProfile`:
|
|||
|
||||
from telethon.tl.functions.account import UpdateProfileRequest
|
||||
|
||||
await client(UpdateProfileRequest(
|
||||
client(UpdateProfileRequest(
|
||||
about='This is a test from Telethon'
|
||||
))
|
||||
|
||||
|
||||
Updating your username
|
||||
======================
|
||||
**********************
|
||||
|
||||
You need to use :tl:`account.UpdateUsername`:
|
||||
|
||||
|
|
@ -55,11 +55,11 @@ You need to use :tl:`account.UpdateUsername`:
|
|||
|
||||
from telethon.tl.functions.account import UpdateUsernameRequest
|
||||
|
||||
await client(UpdateUsernameRequest('new_username'))
|
||||
client(UpdateUsernameRequest('new_username'))
|
||||
|
||||
|
||||
Updating your profile photo
|
||||
===========================
|
||||
***************************
|
||||
|
||||
The easiest way is to upload a new file and use that as the profile photo
|
||||
through :tl:`UploadProfilePhoto`:
|
||||
|
|
@ -69,6 +69,6 @@ through :tl:`UploadProfilePhoto`:
|
|||
|
||||
from telethon.tl.functions.photos import UploadProfilePhotoRequest
|
||||
|
||||
await client(UploadProfilePhotoRequest(
|
||||
await client.upload_file('/path/to/some/file')
|
||||
))
|
||||
client(UploadProfilePhotoRequest(
|
||||
client.upload_file('/path/to/some/file')
|
||||
)))
|
||||
140
readthedocs/extra/examples/working-with-messages.rst
Normal file
140
readthedocs/extra/examples/working-with-messages.rst
Normal file
|
|
@ -0,0 +1,140 @@
|
|||
=====================
|
||||
Working with messages
|
||||
=====================
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
These examples assume you have read :ref:`accessing-the-full-api`.
|
||||
|
||||
.. contents::
|
||||
|
||||
|
||||
Forwarding messages
|
||||
*******************
|
||||
|
||||
.. note::
|
||||
|
||||
Use the `telethon.client.messages.MessageMethods.forward_messages`
|
||||
friendly method instead unless you have a better reason not to!
|
||||
|
||||
This method automatically accepts either a single message or many of them.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# If you only have the message IDs
|
||||
client.forward_messages(
|
||||
entity, # to which entity you are forwarding the messages
|
||||
message_ids, # the IDs of the messages (or message) to forward
|
||||
from_entity # who sent the messages?
|
||||
)
|
||||
|
||||
# If you have ``Message`` objects
|
||||
client.forward_messages(
|
||||
entity, # to which entity you are forwarding the messages
|
||||
messages # the messages (or message) to forward
|
||||
)
|
||||
|
||||
# You can also do it manually if you prefer
|
||||
from telethon.tl.functions.messages import ForwardMessagesRequest
|
||||
|
||||
messages = foo() # retrieve a few messages (or even one, in a list)
|
||||
from_entity = bar()
|
||||
to_entity = baz()
|
||||
|
||||
client(ForwardMessagesRequest(
|
||||
from_peer=from_entity, # who sent these messages?
|
||||
id=[msg.id for msg in messages], # which are the messages?
|
||||
to_peer=to_entity # who are we forwarding them to?
|
||||
))
|
||||
|
||||
The named arguments are there for clarity, although they're not needed because
|
||||
they appear in order. You can obviously just wrap a single message on the list
|
||||
too, if that's all you have.
|
||||
|
||||
|
||||
Searching Messages
|
||||
*******************
|
||||
|
||||
.. note::
|
||||
|
||||
Use the `telethon.client.messages.MessageMethods.iter_messages`
|
||||
friendly method instead unless you have a better reason not to!
|
||||
|
||||
This method has ``search`` and ``filter`` parameters that will
|
||||
suit your needs.
|
||||
|
||||
Messages are searched through the obvious :tl:`SearchRequest`, but you may run
|
||||
into issues_. A valid example would be:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.tl.functions.messages import SearchRequest
|
||||
from telethon.tl.types import InputMessagesFilterEmpty
|
||||
|
||||
filter = InputMessagesFilterEmpty()
|
||||
result = client(SearchRequest(
|
||||
peer=peer, # On which chat/conversation
|
||||
q='query', # What to search for
|
||||
filter=filter, # Filter to use (maybe filter for media)
|
||||
min_date=None, # Minimum date
|
||||
max_date=None, # Maximum date
|
||||
offset_id=0, # ID of the message to use as offset
|
||||
add_offset=0, # Additional offset
|
||||
limit=10, # How many results
|
||||
max_id=0, # Maximum message ID
|
||||
min_id=0, # Minimum message ID
|
||||
from_id=None, # Who must have sent the message (peer)
|
||||
hash=0 # Special number to return nothing on no-change
|
||||
))
|
||||
|
||||
It's important to note that the optional parameter ``from_id`` could have
|
||||
been omitted (defaulting to ``None``). Changing it to :tl:`InputUserEmpty`, as one
|
||||
could think to specify "no user", won't work because this parameter is a flag,
|
||||
and it being unspecified has a different meaning.
|
||||
|
||||
If one were to set ``from_id=InputUserEmpty()``, it would filter messages
|
||||
from "empty" senders, which would likely match no users.
|
||||
|
||||
If you get a ``ChatAdminRequiredError`` on a channel, it's probably because
|
||||
you tried setting the ``from_id`` filter, and as the error says, you can't
|
||||
do that. Leave it set to ``None`` and it should work.
|
||||
|
||||
As with every method, make sure you use the right ID/hash combination for
|
||||
your :tl:`InputUser` or :tl:`InputChat`, or you'll likely run into errors like
|
||||
``UserIdInvalidError``.
|
||||
|
||||
|
||||
Sending stickers
|
||||
****************
|
||||
|
||||
Stickers are nothing else than ``files``, and when you successfully retrieve
|
||||
the stickers for a certain sticker set, all you will have are ``handles`` to
|
||||
these files. Remember, the files Telegram holds on their servers can be
|
||||
referenced through this pair of ID/hash (unique per user), and you need to
|
||||
use this handle when sending a "document" message. This working example will
|
||||
send yourself the very first sticker you have:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Get all the sticker sets this user has
|
||||
from telethon.tl.functions.messages import GetAllStickersRequest
|
||||
sticker_sets = client(GetAllStickersRequest(0))
|
||||
|
||||
# Choose a sticker set
|
||||
from telethon.tl.functions.messages import GetStickerSetRequest
|
||||
from telethon.tl.types import InputStickerSetID
|
||||
sticker_set = sticker_sets.sets[0]
|
||||
|
||||
# Get the stickers for this sticker set
|
||||
stickers = client(GetStickerSetRequest(
|
||||
stickerset=InputStickerSetID(
|
||||
id=sticker_set.id, access_hash=sticker_set.access_hash
|
||||
)
|
||||
))
|
||||
|
||||
# Stickers are nothing more than files, so send that
|
||||
client.send_file('me', stickers.documents[0])
|
||||
|
||||
|
||||
.. _issues: https://github.com/LonamiWebs/Telethon/issues/215
|
||||
|
|
@ -0,0 +1,27 @@
|
|||
========================================
|
||||
Deleted, Limited or Deactivated Accounts
|
||||
========================================
|
||||
|
||||
If you're from Iran or Russia, we have bad news for you. Telegram is much more
|
||||
likely to ban these numbers, as they are often used to spam other accounts,
|
||||
likely through the use of libraries like this one. The best advice we can
|
||||
give you is to not abuse the API, like calling many requests really quickly,
|
||||
and to sign up with these phones through an official application.
|
||||
|
||||
We have also had reports from Kazakhstan and China, where connecting
|
||||
would fail. To solve these connection problems, you should use a proxy.
|
||||
|
||||
Telegram may also ban virtual (VoIP) phone numbers,
|
||||
as again, they're likely to be used for spam.
|
||||
|
||||
If you want to check if your account has been limited,
|
||||
simply send a private message to `@SpamBot`__ through Telegram itself.
|
||||
You should notice this by getting errors like ``PeerFloodError``,
|
||||
which means you're limited, for instance,
|
||||
when sending a message to some accounts but not others.
|
||||
|
||||
For more discussion, please see `issue 297`__.
|
||||
|
||||
|
||||
__ https://t.me/SpamBot
|
||||
__ https://github.com/LonamiWebs/Telethon/issues/297
|
||||
40
readthedocs/extra/troubleshooting/enable-logging.rst
Normal file
40
readthedocs/extra/troubleshooting/enable-logging.rst
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
================
|
||||
Enabling Logging
|
||||
================
|
||||
|
||||
Telethon makes use of the `logging`__ module, and you can enable it as follows:
|
||||
|
||||
.. code:: python
|
||||
|
||||
import logging
|
||||
logging.basicConfig(level=logging.DEBUG)
|
||||
|
||||
The library has the `NullHandler`__ added by default so that no log calls
|
||||
will be printed unless you explicitly enable it.
|
||||
|
||||
You can also `use the module`__ on your own project very easily:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import logging
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
logger.debug('Debug messages')
|
||||
logger.info('Useful information')
|
||||
logger.warning('This is a warning!')
|
||||
|
||||
|
||||
If you want to enable ``logging`` for your project *but* use a different
|
||||
log level for the library:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import logging
|
||||
logging.basicConfig(level=logging.DEBUG)
|
||||
# For instance, show only warnings and above
|
||||
logging.getLogger('telethon').setLevel(level=logging.WARNING)
|
||||
|
||||
|
||||
__ https://docs.python.org/3/library/logging.html
|
||||
__ https://docs.python.org/3/howto/logging.html#configuring-logging-for-a-library
|
||||
__ https://docs.python.org/3/howto/logging.html
|
||||
29
readthedocs/extra/troubleshooting/rpc-errors.rst
Normal file
29
readthedocs/extra/troubleshooting/rpc-errors.rst
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
==========
|
||||
RPC Errors
|
||||
==========
|
||||
|
||||
RPC stands for Remote Procedure Call, and when the library raises
|
||||
a ``RPCError``, it's because you have invoked some of the API
|
||||
methods incorrectly (wrong parameters, wrong permissions, or even
|
||||
something went wrong on Telegram's server). All the errors are
|
||||
available in :ref:`telethon-errors-package`, but some examples are:
|
||||
|
||||
- ``FloodWaitError`` (420), the same request was repeated many times.
|
||||
Must wait ``.seconds`` (you can access this parameter).
|
||||
- ``SessionPasswordNeededError``, if you have setup two-steps
|
||||
verification on Telegram.
|
||||
- ``CdnFileTamperedError``, if the media you were trying to download
|
||||
from a CDN has been altered.
|
||||
- ``ChatAdminRequiredError``, you don't have permissions to perform
|
||||
said operation on a chat or channel. Try avoiding filters, i.e. when
|
||||
searching messages.
|
||||
|
||||
The generic classes for different error codes are:
|
||||
|
||||
- ``InvalidDCError`` (303), the request must be repeated on another DC.
|
||||
- ``BadRequestError`` (400), the request contained errors.
|
||||
- ``UnauthorizedError`` (401), the user is not authorized yet.
|
||||
- ``ForbiddenError`` (403), privacy violation error.
|
||||
- ``NotFoundError`` (404), make sure you're invoking ``Request``\ 's!
|
||||
|
||||
If the error is not recognised, it will only be an ``RPCError``.
|
||||
|
|
@ -10,7 +10,7 @@ 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/>`__,
|
||||
`look for the method you need <https://lonamiwebs.github.io/Telethon/>`__,
|
||||
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
|
||||
|
|
@ -1,32 +1,28 @@
|
|||
========================
|
||||
Telethon's Documentation
|
||||
========================
|
||||
.. Telethon documentation master file, created by
|
||||
sphinx-quickstart on Fri Nov 17 15:36:11 2017.
|
||||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon.sync import TelegramClient, events
|
||||
|
||||
with TelegramClient('name', api_id, api_hash) as client:
|
||||
client.send_message('me', 'Hello, myself!')
|
||||
print(client.download_profile_photo('me'))
|
||||
|
||||
@client.on(events.NewMessage(pattern='(?i).*Hello'))
|
||||
async def handler(event):
|
||||
await event.reply('Hey!')
|
||||
|
||||
client.run_until_disconnected()
|
||||
====================================
|
||||
Welcome to Telethon's documentation!
|
||||
====================================
|
||||
|
||||
|
||||
* Are you new here? Jump straight into :ref:`installation`!
|
||||
* Looking for the method reference? See :ref:`client-ref`.
|
||||
* Did you upgrade the library? Please read :ref:`changelog`.
|
||||
* Used Telethon before v1.0? See :ref:`compatibility-and-convenience`.
|
||||
* Coming from Bot API or want to create new bots? See :ref:`botapi`.
|
||||
* Need the full API reference? https://tl.telethon.dev/.
|
||||
Pure Python 3 Telegram client library.
|
||||
Official Site `here <https://lonamiwebs.github.io/Telethon>`_.
|
||||
Please follow the links on the index below to navigate from here,
|
||||
or use the menu on the left. Remember to read the :ref:`changelog`
|
||||
when you upgrade!
|
||||
|
||||
.. important::
|
||||
|
||||
* Are you new here? Jump straight into :ref:`getting-started`!
|
||||
* Looking for available friendly methods? See :ref:`telethon-client`.
|
||||
* Used Telethon before v1.0? See :ref:`compatibility-and-convenience`.
|
||||
|
||||
|
||||
What is this?
|
||||
-------------
|
||||
*************
|
||||
|
||||
Telegram is a popular messaging application. This library is meant
|
||||
to make it easy for you to write Python programs that can interact
|
||||
|
|
@ -34,87 +30,94 @@ with Telegram. Think of it as a wrapper that has already done the
|
|||
heavy job for you, so you can focus on developing an application.
|
||||
|
||||
|
||||
How should I use the documentation?
|
||||
-----------------------------------
|
||||
|
||||
If you are getting started with the library, you should follow the
|
||||
documentation in order by pressing the "Next" button at the bottom-right
|
||||
of every page.
|
||||
|
||||
You can also use the menu on the left to quickly skip over sections.
|
||||
.. _installation-and-usage:
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:caption: First Steps
|
||||
:maxdepth: 2
|
||||
:caption: Installation and Simple Usage
|
||||
|
||||
basic/installation
|
||||
basic/signing-in
|
||||
basic/quick-start
|
||||
basic/updates
|
||||
basic/next-steps
|
||||
extra/basic/getting-started
|
||||
extra/basic/installation
|
||||
extra/basic/creating-a-client
|
||||
extra/basic/telegram-client
|
||||
extra/basic/entities
|
||||
extra/basic/working-with-updates
|
||||
extra/basic/compatibility-and-convenience
|
||||
|
||||
|
||||
.. _Advanced-usage:
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:caption: Quick References
|
||||
:maxdepth: 2
|
||||
:caption: Advanced Usage
|
||||
|
||||
quick-references/faq
|
||||
quick-references/client-reference
|
||||
quick-references/events-reference
|
||||
quick-references/objects-reference
|
||||
extra/advanced-usage/accessing-the-full-api
|
||||
extra/advanced-usage/sessions
|
||||
extra/advanced-usage/update-modes
|
||||
extra/advanced-usage/mastering-telethon
|
||||
extra/advanced-usage/mastering-asyncio
|
||||
|
||||
|
||||
.. _Examples:
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:caption: Concepts
|
||||
:maxdepth: 2
|
||||
:caption: Examples
|
||||
|
||||
concepts/strings
|
||||
concepts/entities
|
||||
concepts/chats-vs-channels
|
||||
concepts/updates
|
||||
concepts/sessions
|
||||
concepts/full-api
|
||||
concepts/errors
|
||||
concepts/botapi-vs-mtproto
|
||||
concepts/asyncio
|
||||
extra/examples/telegram-client
|
||||
extra/examples/working-with-messages
|
||||
extra/examples/chats-and-channels
|
||||
extra/examples/users
|
||||
extra/examples/bots
|
||||
extra/examples/projects-using-telethon
|
||||
|
||||
|
||||
.. _Troubleshooting:
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:caption: Full API Examples
|
||||
:maxdepth: 2
|
||||
:caption: Troubleshooting
|
||||
|
||||
examples/word-of-warning
|
||||
examples/chats-and-channels
|
||||
examples/users
|
||||
examples/working-with-messages
|
||||
extra/troubleshooting/enable-logging
|
||||
extra/troubleshooting/deleted-limited-or-deactivated-accounts
|
||||
extra/troubleshooting/rpc-errors
|
||||
|
||||
|
||||
.. _Developing:
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:caption: Developing
|
||||
:maxdepth: 2
|
||||
:caption: Developing
|
||||
|
||||
developing/philosophy.rst
|
||||
developing/test-servers.rst
|
||||
developing/project-structure.rst
|
||||
developing/coding-style.rst
|
||||
developing/testing.rst
|
||||
developing/understanding-the-type-language.rst
|
||||
developing/tips-for-porting-the-project.rst
|
||||
developing/telegram-api-in-other-languages.rst
|
||||
extra/developing/philosophy.rst
|
||||
extra/developing/api-status.rst
|
||||
extra/developing/test-servers.rst
|
||||
extra/developing/project-structure.rst
|
||||
extra/developing/coding-style.rst
|
||||
extra/developing/understanding-the-type-language.rst
|
||||
extra/developing/tips-for-porting-the-project.rst
|
||||
extra/developing/telegram-api-in-other-languages.rst
|
||||
|
||||
|
||||
.. _More:
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:caption: Miscellaneous
|
||||
:maxdepth: 2
|
||||
:caption: More
|
||||
|
||||
extra/changelog
|
||||
extra/wall-of-shame.rst
|
||||
|
||||
misc/changelog
|
||||
misc/wall-of-shame.rst
|
||||
misc/compatibility-and-convenience
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:caption: Telethon Modules
|
||||
:caption: Telethon modules
|
||||
|
||||
modules/client
|
||||
modules/events
|
||||
modules/custom
|
||||
modules/utils
|
||||
modules/errors
|
||||
modules/sessions
|
||||
modules/network
|
||||
modules/helpers
|
||||
modules
|
||||
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
|
|
|
|||
7
readthedocs/modules.rst
Normal file
7
readthedocs/modules.rst
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
telethon
|
||||
========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
|
||||
telethon
|
||||
|
|
@ -1,163 +0,0 @@
|
|||
==============
|
||||
Custom package
|
||||
==============
|
||||
|
||||
The `telethon.tl.custom` package contains custom classes that the library
|
||||
uses in order to make working with Telegram easier. Only those that you
|
||||
are supposed to use will be documented here. You can use undocumented ones
|
||||
at your own risk.
|
||||
|
||||
More often than not, you don't need to import these (unless you want
|
||||
type hinting), nor do you need to manually create instances of these
|
||||
classes. They are returned by client methods.
|
||||
|
||||
.. contents::
|
||||
|
||||
.. automodule:: telethon.tl.custom
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
AdminLogEvent
|
||||
=============
|
||||
|
||||
.. automodule:: telethon.tl.custom.adminlogevent
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
Button
|
||||
======
|
||||
|
||||
.. automodule:: telethon.tl.custom.button
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
ChatGetter
|
||||
==========
|
||||
|
||||
.. automodule:: telethon.tl.custom.chatgetter
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
Conversation
|
||||
============
|
||||
|
||||
.. automodule:: telethon.tl.custom.conversation
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
Dialog
|
||||
======
|
||||
|
||||
.. automodule:: telethon.tl.custom.dialog
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
Draft
|
||||
=====
|
||||
|
||||
.. automodule:: telethon.tl.custom.draft
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
File
|
||||
====
|
||||
|
||||
.. automodule:: telethon.tl.custom.file
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
Forward
|
||||
=======
|
||||
|
||||
.. automodule:: telethon.tl.custom.forward
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
InlineBuilder
|
||||
=============
|
||||
|
||||
.. automodule:: telethon.tl.custom.inlinebuilder
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
InlineResult
|
||||
============
|
||||
|
||||
.. automodule:: telethon.tl.custom.inlineresult
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
InlineResults
|
||||
=============
|
||||
|
||||
.. automodule:: telethon.tl.custom.inlineresults
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
Message
|
||||
=======
|
||||
|
||||
.. automodule:: telethon.tl.custom.message
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
MessageButton
|
||||
=============
|
||||
|
||||
.. automodule:: telethon.tl.custom.messagebutton
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
ParticipantPermissions
|
||||
======================
|
||||
|
||||
.. automodule:: telethon.tl.custom.participantpermissions
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
QRLogin
|
||||
=======
|
||||
|
||||
.. automodule:: telethon.tl.custom.qrlogin
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
SenderGetter
|
||||
============
|
||||
|
||||
.. automodule:: telethon.tl.custom.sendergetter
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
|
@ -1,20 +0,0 @@
|
|||
.. _telethon-errors:
|
||||
|
||||
==========
|
||||
API Errors
|
||||
==========
|
||||
|
||||
These are the base errors that Telegram's API may raise.
|
||||
|
||||
See :ref:`rpc-errors` for a more in-depth explanation on how to handle all
|
||||
known possible errors and learning to determine what a method may raise.
|
||||
|
||||
.. automodule:: telethon.errors.common
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. automodule:: telethon.errors.rpcbaseerrors
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
|
@ -1,8 +0,0 @@
|
|||
=======
|
||||
Helpers
|
||||
=======
|
||||
|
||||
.. automodule:: telethon.helpers
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
|
@ -1,33 +0,0 @@
|
|||
.. _telethon-network:
|
||||
|
||||
================
|
||||
Connection Modes
|
||||
================
|
||||
|
||||
The only part about network that you should worry about are
|
||||
the different connection modes, which are the following:
|
||||
|
||||
.. automodule:: telethon.network.connection.tcpfull
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. automodule:: telethon.network.connection.tcpabridged
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. automodule:: telethon.network.connection.tcpintermediate
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. automodule:: telethon.network.connection.tcpobfuscated
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. automodule:: telethon.network.connection.http
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
|
@ -1,27 +0,0 @@
|
|||
.. _telethon-sessions:
|
||||
|
||||
========
|
||||
Sessions
|
||||
========
|
||||
|
||||
These are the different built-in session storage that you may subclass.
|
||||
|
||||
.. automodule:: telethon.sessions.abstract
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. automodule:: telethon.sessions.memory
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. automodule:: telethon.sessions.sqlite
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. automodule:: telethon.sessions.string
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
|
@ -1,12 +0,0 @@
|
|||
.. _telethon-utils:
|
||||
|
||||
=========
|
||||
Utilities
|
||||
=========
|
||||
|
||||
These are the utilities that the library has to offer.
|
||||
|
||||
.. automodule:: telethon.utils
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
|
@ -1,202 +0,0 @@
|
|||
.. _client-ref:
|
||||
|
||||
================
|
||||
Client Reference
|
||||
================
|
||||
|
||||
This page contains a summary of all the important methods and properties that
|
||||
you may need when using Telethon. They are sorted by relevance and are not in
|
||||
alphabetical order.
|
||||
|
||||
You should use this page to learn about which methods are available, and
|
||||
if you need a usage example or further description of the arguments, be
|
||||
sure to follow the links.
|
||||
|
||||
.. contents::
|
||||
|
||||
TelegramClient
|
||||
==============
|
||||
|
||||
This is a summary of the methods and
|
||||
properties you will find at :ref:`telethon-client`.
|
||||
|
||||
Auth
|
||||
----
|
||||
|
||||
.. currentmodule:: telethon.client.auth.AuthMethods
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
start
|
||||
send_code_request
|
||||
sign_in
|
||||
qr_login
|
||||
log_out
|
||||
edit_2fa
|
||||
|
||||
Base
|
||||
----
|
||||
|
||||
.. py:currentmodule:: telethon.client.telegrambaseclient.TelegramBaseClient
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
connect
|
||||
disconnect
|
||||
is_connected
|
||||
disconnected
|
||||
loop
|
||||
set_proxy
|
||||
|
||||
Messages
|
||||
--------
|
||||
|
||||
.. py:currentmodule:: telethon.client.messages.MessageMethods
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
send_message
|
||||
edit_message
|
||||
delete_messages
|
||||
forward_messages
|
||||
iter_messages
|
||||
get_messages
|
||||
pin_message
|
||||
unpin_message
|
||||
send_read_acknowledge
|
||||
|
||||
Uploads
|
||||
-------
|
||||
|
||||
.. py:currentmodule:: telethon.client.uploads.UploadMethods
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
send_file
|
||||
upload_file
|
||||
|
||||
Downloads
|
||||
---------
|
||||
|
||||
.. currentmodule:: telethon.client.downloads.DownloadMethods
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
download_media
|
||||
download_profile_photo
|
||||
download_file
|
||||
iter_download
|
||||
|
||||
Dialogs
|
||||
-------
|
||||
|
||||
.. py:currentmodule:: telethon.client.dialogs.DialogMethods
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
iter_dialogs
|
||||
get_dialogs
|
||||
edit_folder
|
||||
iter_drafts
|
||||
get_drafts
|
||||
delete_dialog
|
||||
conversation
|
||||
|
||||
Users
|
||||
-----
|
||||
|
||||
.. py:currentmodule:: telethon.client.users.UserMethods
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
get_me
|
||||
is_bot
|
||||
is_user_authorized
|
||||
get_entity
|
||||
get_input_entity
|
||||
get_peer_id
|
||||
|
||||
Chats
|
||||
-----
|
||||
|
||||
.. currentmodule:: telethon.client.chats.ChatMethods
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
iter_participants
|
||||
get_participants
|
||||
kick_participant
|
||||
iter_admin_log
|
||||
get_admin_log
|
||||
iter_profile_photos
|
||||
get_profile_photos
|
||||
edit_admin
|
||||
edit_permissions
|
||||
get_permissions
|
||||
get_stats
|
||||
action
|
||||
|
||||
Parse Mode
|
||||
----------
|
||||
|
||||
.. py:currentmodule:: telethon.client.messageparse.MessageParseMethods
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
parse_mode
|
||||
|
||||
Updates
|
||||
-------
|
||||
|
||||
.. py:currentmodule:: telethon.client.updates.UpdateMethods
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
on
|
||||
run_until_disconnected
|
||||
add_event_handler
|
||||
remove_event_handler
|
||||
list_event_handlers
|
||||
catch_up
|
||||
set_receive_updates
|
||||
|
||||
Bots
|
||||
----
|
||||
|
||||
.. currentmodule:: telethon.client.bots.BotMethods
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
inline_query
|
||||
|
||||
Buttons
|
||||
-------
|
||||
|
||||
.. currentmodule:: telethon.client.buttons.ButtonMethods
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
build_reply_markup
|
||||
|
||||
Account
|
||||
-------
|
||||
|
||||
.. currentmodule:: telethon.client.account.AccountMethods
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
takeout
|
||||
end_takeout
|
||||
|
|
@ -1,247 +0,0 @@
|
|||
================
|
||||
Events Reference
|
||||
================
|
||||
|
||||
Here you will find a quick summary of all the methods
|
||||
and properties that you can access when working with events.
|
||||
|
||||
You can access the client that creates this event by doing
|
||||
``event.client``, and you should view the description of the
|
||||
events to find out what arguments it allows on creation and
|
||||
its **attributes** (the properties will be shown here).
|
||||
|
||||
.. important::
|
||||
|
||||
Remember that **all events base** `ChatGetter
|
||||
<telethon.tl.custom.chatgetter.ChatGetter>`! Please see :ref:`faq`
|
||||
if you don't know what this means or the implications of it.
|
||||
|
||||
.. contents::
|
||||
|
||||
|
||||
NewMessage
|
||||
==========
|
||||
|
||||
Occurs whenever a new text message or a message with media arrives.
|
||||
|
||||
.. note::
|
||||
|
||||
The new message event **should be treated as** a
|
||||
normal `Message <telethon.tl.custom.message.Message>`, with
|
||||
the following exceptions:
|
||||
|
||||
* ``pattern_match`` is the match object returned by ``pattern=``.
|
||||
* ``message`` is **not** the message string. It's the `Message
|
||||
<telethon.tl.custom.message.Message>` object.
|
||||
|
||||
Remember, this event is just a proxy over the message, so while
|
||||
you won't see its attributes and properties, you can still access
|
||||
them. Please see the full documentation for examples.
|
||||
|
||||
Full documentation for the `NewMessage
|
||||
<telethon.events.newmessage.NewMessage>`.
|
||||
|
||||
|
||||
MessageEdited
|
||||
=============
|
||||
|
||||
Occurs whenever a message is edited. Just like `NewMessage
|
||||
<telethon.events.newmessage.NewMessage>`, you should treat
|
||||
this event as a `Message <telethon.tl.custom.message.Message>`.
|
||||
|
||||
Full documentation for the `MessageEdited
|
||||
<telethon.events.messageedited.MessageEdited>`.
|
||||
|
||||
|
||||
MessageDeleted
|
||||
==============
|
||||
|
||||
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
|
||||
was deleted.
|
||||
|
||||
It only has the ``deleted_id`` and ``deleted_ids`` attributes
|
||||
(in addition to the chat if the deletion happened in a channel).
|
||||
|
||||
Full documentation for the `MessageDeleted
|
||||
<telethon.events.messagedeleted.MessageDeleted>`.
|
||||
|
||||
|
||||
MessageRead
|
||||
===========
|
||||
|
||||
Occurs whenever one or more messages are read in a chat.
|
||||
|
||||
Full documentation for the `MessageRead
|
||||
<telethon.events.messageread.MessageRead>`.
|
||||
|
||||
.. currentmodule:: telethon.events.messageread.MessageRead.Event
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
inbox
|
||||
message_ids
|
||||
|
||||
get_messages
|
||||
is_read
|
||||
|
||||
|
||||
ChatAction
|
||||
==========
|
||||
|
||||
Occurs on certain chat actions, such as chat title changes,
|
||||
user join or leaves, pinned messages, photo changes, etc.
|
||||
|
||||
Full documentation for the `ChatAction
|
||||
<telethon.events.chataction.ChatAction>`.
|
||||
|
||||
.. currentmodule:: telethon.events.chataction.ChatAction.Event
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
added_by
|
||||
kicked_by
|
||||
user
|
||||
input_user
|
||||
user_id
|
||||
users
|
||||
input_users
|
||||
user_ids
|
||||
|
||||
respond
|
||||
reply
|
||||
delete
|
||||
get_pinned_message
|
||||
get_added_by
|
||||
get_kicked_by
|
||||
get_user
|
||||
get_input_user
|
||||
get_users
|
||||
get_input_users
|
||||
|
||||
|
||||
UserUpdate
|
||||
==========
|
||||
|
||||
Occurs whenever a user goes online, starts typing, etc.
|
||||
|
||||
Full documentation for the `UserUpdate
|
||||
<telethon.events.userupdate.UserUpdate>`.
|
||||
|
||||
.. currentmodule:: telethon.events.userupdate.UserUpdate.Event
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
user
|
||||
input_user
|
||||
user_id
|
||||
|
||||
get_user
|
||||
get_input_user
|
||||
|
||||
typing
|
||||
uploading
|
||||
recording
|
||||
playing
|
||||
cancel
|
||||
geo
|
||||
audio
|
||||
round
|
||||
video
|
||||
contact
|
||||
document
|
||||
photo
|
||||
last_seen
|
||||
until
|
||||
online
|
||||
recently
|
||||
within_weeks
|
||||
within_months
|
||||
|
||||
|
||||
CallbackQuery
|
||||
=============
|
||||
|
||||
Occurs whenever you sign in as a bot and a user
|
||||
clicks one of the inline buttons on your messages.
|
||||
|
||||
Full documentation for the `CallbackQuery
|
||||
<telethon.events.callbackquery.CallbackQuery>`.
|
||||
|
||||
.. currentmodule:: telethon.events.callbackquery.CallbackQuery.Event
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
id
|
||||
message_id
|
||||
data
|
||||
chat_instance
|
||||
via_inline
|
||||
|
||||
respond
|
||||
reply
|
||||
edit
|
||||
delete
|
||||
answer
|
||||
get_message
|
||||
|
||||
InlineQuery
|
||||
===========
|
||||
|
||||
Occurs whenever you sign in as a bot and a user
|
||||
sends an inline query such as ``@bot query``.
|
||||
|
||||
Full documentation for the `InlineQuery
|
||||
<telethon.events.inlinequery.InlineQuery>`.
|
||||
|
||||
.. currentmodule:: telethon.events.inlinequery.InlineQuery.Event
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
id
|
||||
text
|
||||
offset
|
||||
geo
|
||||
builder
|
||||
|
||||
answer
|
||||
|
||||
Album
|
||||
=====
|
||||
|
||||
Occurs whenever you receive an entire album.
|
||||
|
||||
Full documentation for the `Album
|
||||
<telethon.events.album.Album>`.
|
||||
|
||||
.. currentmodule:: telethon.events.album.Album.Event
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
grouped_id
|
||||
text
|
||||
raw_text
|
||||
is_reply
|
||||
forward
|
||||
|
||||
get_reply_message
|
||||
respond
|
||||
reply
|
||||
forward_to
|
||||
edit
|
||||
delete
|
||||
mark_read
|
||||
pin
|
||||
|
||||
Raw
|
||||
===
|
||||
|
||||
Raw events are not actual events. Instead, they are the raw
|
||||
:tl:`Update` object that Telegram sends. You normally shouldn't
|
||||
need these.
|
||||
|
|
@ -1,423 +0,0 @@
|
|||
.. _faq:
|
||||
|
||||
===
|
||||
FAQ
|
||||
===
|
||||
|
||||
Let's start the quick references section with some useful tips to keep in
|
||||
mind, with the hope that you will understand why certain things work the
|
||||
way that they do.
|
||||
|
||||
.. contents::
|
||||
|
||||
|
||||
Code without errors doesn't work
|
||||
================================
|
||||
|
||||
Then it probably has errors, but you haven't enabled logging yet.
|
||||
To enable logging, at the following code to the top of your main file:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import logging
|
||||
logging.basicConfig(format='[%(levelname) %(asctime)s] %(name)s: %(message)s',
|
||||
level=logging.WARNING)
|
||||
|
||||
You can change the logging level to be something different, from less to more information:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
level=logging.CRITICAL # won't show errors (same as disabled)
|
||||
level=logging.ERROR # will only show errors that you didn't handle
|
||||
level=logging.WARNING # will also show messages with medium severity, such as internal Telegram issues
|
||||
level=logging.INFO # will also show informational messages, such as connection or disconnections
|
||||
level=logging.DEBUG # will show a lot of output to help debugging issues in the library
|
||||
|
||||
See the official Python documentation for more information on logging_.
|
||||
|
||||
|
||||
How can I except FloodWaitError?
|
||||
================================
|
||||
|
||||
You can use all errors from the API by importing:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import errors
|
||||
|
||||
And except them as such:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
try:
|
||||
await client.send_message(chat, 'Hi')
|
||||
except errors.FloodWaitError as e:
|
||||
# e.seconds is how many seconds you have
|
||||
# to wait before making the request again.
|
||||
print('Flood for', e.seconds)
|
||||
|
||||
|
||||
My account was deleted/limited when using the library
|
||||
=====================================================
|
||||
|
||||
First and foremost, **this is not a problem exclusive to Telethon.
|
||||
Any third-party library is prone to cause the accounts to appear banned.**
|
||||
Even official applications can make Telegram ban an account under certain
|
||||
circumstances. Third-party libraries such as Telethon are a lot easier to
|
||||
use, and as such, they are misused to spam, which causes Telegram to learn
|
||||
certain patterns and ban suspicious activity.
|
||||
|
||||
There is no point in Telethon trying to circumvent this. Even if it succeeded,
|
||||
spammers would then abuse the library again, and the cycle would repeat.
|
||||
|
||||
The library will only do things that you tell it to do. If you use
|
||||
the library with bad intentions, Telegram will hopefully ban you.
|
||||
|
||||
However, you may also be part of a limited country, such as Iran or Russia.
|
||||
In that case, we have bad news for you. Telegram is much more likely to ban
|
||||
these numbers, as they are often used to spam other accounts, likely through
|
||||
the use of libraries like this one. The best advice we can give you is to not
|
||||
abuse the API, like calling many requests really quickly.
|
||||
|
||||
We have also had reports from Kazakhstan and China, where connecting
|
||||
would fail. To solve these connection problems, you should use a proxy.
|
||||
|
||||
Telegram may also ban virtual (VoIP) phone numbers,
|
||||
as again, they're likely to be used for spam.
|
||||
|
||||
More recently (year 2023 onwards), Telegram has started putting a lot more
|
||||
measures to prevent spam (with even additions such as anonymous participants
|
||||
in groups or the inability to fetch group members at all). This means some
|
||||
of the anti-spam measures have gotten more aggressive.
|
||||
|
||||
The recommendation has usually been to use the library only on well-established
|
||||
accounts (and not an account you just created), and to not perform actions that
|
||||
could be seen as abuse. Telegram decides what those actions are, and they're
|
||||
free to change how they operate at any time.
|
||||
|
||||
If you want to check if your account has been limited,
|
||||
simply send a private message to `@SpamBot`_ through Telegram itself.
|
||||
You should notice this by getting errors like ``PeerFloodError``,
|
||||
which means you're limited, for instance,
|
||||
when sending a message to some accounts but not others.
|
||||
|
||||
For more discussion, please see `issue 297`_.
|
||||
|
||||
|
||||
How can I use a proxy?
|
||||
======================
|
||||
|
||||
This was one of the first things described in :ref:`signing-in`.
|
||||
|
||||
|
||||
How do I access a field?
|
||||
========================
|
||||
|
||||
This is basic Python knowledge. You should use the dot operator:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
me = await client.get_me()
|
||||
print(me.username)
|
||||
# ^ we used the dot operator to access the username attribute
|
||||
|
||||
result = await client(functions.photos.GetUserPhotosRequest(
|
||||
user_id='me',
|
||||
offset=0,
|
||||
max_id=0,
|
||||
limit=100
|
||||
))
|
||||
|
||||
# Working with list is also pretty basic
|
||||
print(result.photos[0].sizes[-1].type)
|
||||
# ^ ^ ^ ^ ^
|
||||
# | | | | \ type
|
||||
# | | | \ last size
|
||||
# | | \ list of sizes
|
||||
# access | \ first photo from the list
|
||||
# the... \ list of photos
|
||||
#
|
||||
# To print all, you could do (or mix-and-match):
|
||||
for photo in result.photos:
|
||||
for size in photo.sizes:
|
||||
print(size.type)
|
||||
|
||||
|
||||
AttributeError: 'coroutine' object has no attribute 'id'
|
||||
========================================================
|
||||
|
||||
You either forgot to:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import telethon.sync
|
||||
# ^^^^^ import sync
|
||||
|
||||
Or:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
async def handler(event):
|
||||
me = await client.get_me()
|
||||
# ^^^^^ note the await
|
||||
print(me.username)
|
||||
|
||||
|
||||
sqlite3.OperationalError: database is locked
|
||||
============================================
|
||||
|
||||
An older process is still running and is using the same ``'session'`` file.
|
||||
|
||||
This error occurs when **two or more clients use the same session**,
|
||||
that is, when you write the same session name to be used in the client:
|
||||
|
||||
* You have an older process using the same session file.
|
||||
* You have two different scripts running (interactive sessions count too).
|
||||
* You have two clients in the same script running at the same time.
|
||||
|
||||
The solution is, if you need two clients, use two sessions. If the
|
||||
problem persists and you're on Linux, you can use ``fuser my.session``
|
||||
to find out the process locking the file. As a last resort, you can
|
||||
reboot your system.
|
||||
|
||||
If you really dislike SQLite, use a different session storage. There
|
||||
is an entire section covering that at :ref:`sessions`.
|
||||
|
||||
|
||||
event.chat or event.sender is None
|
||||
==================================
|
||||
|
||||
Telegram doesn't always send this information in order to save bandwidth.
|
||||
If you need the information, you should fetch it yourself, since the library
|
||||
won't do unnecessary work unless you need to:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
async def handler(event):
|
||||
chat = await event.get_chat()
|
||||
sender = await event.get_sender()
|
||||
|
||||
|
||||
File download is slow or sending files takes too long
|
||||
=====================================================
|
||||
|
||||
The communication with Telegram is encrypted. Encryption requires a lot of
|
||||
math, and doing it in pure Python is very slow. ``cryptg`` is a library which
|
||||
containns the encryption functions used by Telethon. If it is installed (via
|
||||
``pip install cryptg``), it will automatically be used and should provide
|
||||
a considerable speed boost. You can know whether it's used by configuring
|
||||
``logging`` (at ``INFO`` level or lower) *before* importing ``telethon``.
|
||||
|
||||
Note that the library does *not* download or upload files in parallel, which
|
||||
can also help with the speed of downloading or uploading a single file. There
|
||||
are snippets online implementing that. The reason why this is not built-in
|
||||
is because the limiting factor in the long run are ``FloodWaitError``, and
|
||||
using parallel download or uploads only makes them occur sooner.
|
||||
|
||||
|
||||
What does "Server sent a very new message with ID" mean?
|
||||
========================================================
|
||||
|
||||
You may also see this error as "Server sent a very old message with ID".
|
||||
|
||||
This is a security feature from Telethon that cannot be disabled and is
|
||||
meant to protect you against replay attacks.
|
||||
|
||||
When this message is incorrectly reported as a "bug",
|
||||
the most common patterns seem to be:
|
||||
|
||||
* Your system time is incorrect.
|
||||
* The proxy you're using may be interfering somehow.
|
||||
* The Telethon session is being used or has been used from somewhere else.
|
||||
Make sure that you created the session from Telethon, and are not using the
|
||||
same session anywhere else. If you need to use the same account from
|
||||
multiple places, login and use a different session for each place you need.
|
||||
|
||||
|
||||
What does "Server replied with a wrong session ID" mean?
|
||||
========================================================
|
||||
|
||||
This is a security feature from Telethon that cannot be disabled and is
|
||||
meant to protect you against unwanted session reuse.
|
||||
|
||||
When this message is reported as a "bug", the most common patterns seem to be:
|
||||
|
||||
* The proxy you're using may be interfering somehow.
|
||||
* The Telethon session is being used or has been used from somewhere else.
|
||||
Make sure that you created the session from Telethon, and are not using the
|
||||
same session anywhere else. If you need to use the same account from
|
||||
multiple places, login and use a different session for each place you need.
|
||||
* You may be using multiple connections to the Telegram server, which seems
|
||||
to confuse Telegram.
|
||||
|
||||
Most of the time it should be safe to ignore this warning. If the library
|
||||
still doesn't behave correctly, make sure to check if any of the above bullet
|
||||
points applies in your case and try to work around it.
|
||||
|
||||
If the issue persists and there is a way to reliably reproduce this error,
|
||||
please add a comment with any additional details you can provide to
|
||||
`issue 3759`_, and perhaps some additional investigation can be done
|
||||
(but it's unlikely, as Telegram *is* sending unexpected data).
|
||||
|
||||
|
||||
What does "Could not find a matching Constructor ID for the TLObject" mean?
|
||||
===========================================================================
|
||||
|
||||
Telegram uses "layers", which you can think of as "versions" of the API they
|
||||
offer. When Telethon reads responses that the Telegram servers send, these
|
||||
need to be deserialized (into what Telethon calls "TLObjects").
|
||||
|
||||
Every Telethon version understands a single Telegram layer. When Telethon
|
||||
connects to Telegram, both agree on the layer to use. If the layers don't
|
||||
match, Telegram may send certain objects which Telethon no longer understands.
|
||||
|
||||
When this message is reported as a "bug", the most common patterns seem to be
|
||||
that the Telethon session is being used or has been used from somewhere else.
|
||||
Make sure that you created the session from Telethon, and are not using the
|
||||
same session anywhere else. If you need to use the same account from
|
||||
multiple places, login and use a different session for each place you need.
|
||||
|
||||
|
||||
What does "Task was destroyed but it is pending" mean?
|
||||
======================================================
|
||||
|
||||
Your script likely finished abruptly, the ``asyncio`` event loop got
|
||||
destroyed, and the library did not get a chance to properly close the
|
||||
connection and close the session.
|
||||
|
||||
Make sure you're either using the context manager for the client or always
|
||||
call ``await client.disconnect()`` (by e.g. using a ``try/finally``).
|
||||
|
||||
|
||||
What does "The asyncio event loop must not change after connection" mean?
|
||||
=========================================================================
|
||||
|
||||
Telethon uses ``asyncio``, and makes use of things like tasks and queues
|
||||
internally to manage the connection to the server and match responses to the
|
||||
requests you make. Most of them are initialized after the client is connected.
|
||||
|
||||
For example, if the library expects a result to a request made in loop A, but
|
||||
you attempt to get that result in loop B, you will very likely find a deadlock.
|
||||
To avoid a deadlock, the library checks to make sure the loop in use is the
|
||||
same as the one used to initialize everything, and if not, it throws an error.
|
||||
|
||||
The most common cause is ``asyncio.run``, since it creates a new event loop.
|
||||
If you ``asyncio.run`` a function to create the client and set it up, and then
|
||||
you ``asyncio.run`` another function to do work, things won't work, so the
|
||||
library throws an error early to let you know something is wrong.
|
||||
|
||||
Instead, it's often a good idea to have a single ``async def main`` and simply
|
||||
``asyncio.run()`` it and do all the work there. From it, you're also able to
|
||||
call other ``async def`` without having to touch ``asyncio.run`` again:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# It's fine to create the client outside as long as you don't connect
|
||||
client = TelegramClient(...)
|
||||
|
||||
async def main():
|
||||
# Now the client will connect, so the loop must not change from now on.
|
||||
# But as long as you do all the work inside main, including calling
|
||||
# other async functions, things will work.
|
||||
async with client:
|
||||
....
|
||||
|
||||
if __name__ == '__main__':
|
||||
asyncio.run(main())
|
||||
|
||||
Be sure to read the ``asyncio`` documentation if you want a better
|
||||
understanding of event loop, tasks, and what functions you can use.
|
||||
|
||||
|
||||
What does "bases ChatGetter" mean?
|
||||
==================================
|
||||
|
||||
In Python, classes can base others. This is called `inheritance
|
||||
<https://ddg.gg/python%20inheritance>`_. What it means is that
|
||||
"if a class bases another, you can use the other's methods too".
|
||||
|
||||
For example, `Message <telethon.tl.custom.message.Message>` *bases*
|
||||
`ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>`. In turn,
|
||||
`ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>` defines
|
||||
things like `obj.chat_id <telethon.tl.custom.chatgetter.ChatGetter>`.
|
||||
|
||||
So if you have a message, you can access that too:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# ChatGetter has a chat_id property, and Message bases ChatGetter.
|
||||
# Thus you can use ChatGetter properties and methods from Message
|
||||
print(message.chat_id)
|
||||
|
||||
|
||||
Telegram has a lot to offer, and inheritance helps the library reduce
|
||||
boilerplate, so it's important to know this concept. For newcomers,
|
||||
this may be a problem, so we explain what it means here in the FAQ.
|
||||
|
||||
Can I send files by ID?
|
||||
=======================
|
||||
|
||||
When people talk about IDs, they often refer to one of two things:
|
||||
the integer ID inside media, and a random-looking long string.
|
||||
|
||||
You cannot use the integer ID to send media. Generally speaking, sending media
|
||||
requires a combination of ID, ``access_hash`` and ``file_reference``.
|
||||
The first two are integers, while the last one is a random ``bytes`` sequence.
|
||||
|
||||
* The integer ``id`` will always be the same for every account, so every user
|
||||
or bot looking at a particular media file, will see a consistent ID.
|
||||
* The ``access_hash`` will always be the same for a given account, but
|
||||
different accounts will each see their own, different ``access_hash``.
|
||||
This makes it impossible to get media object from one account and use it in
|
||||
another. The other account must fetch the media object itself.
|
||||
* The ``file_reference`` is random for everyone and will only work for a few
|
||||
hours before it expires. It must be refetched before the media can be used
|
||||
(to either resend the media or download it).
|
||||
|
||||
The second type of "`file ID <https://core.telegram.org/bots/api#inputfile>`_"
|
||||
people refer to is a concept from the HTTP Bot API. It's a custom format which
|
||||
encodes enough information to use the media.
|
||||
|
||||
Telethon provides an old version of these HTTP Bot API-style file IDs via
|
||||
``message.file.id``, however, this feature is no longer maintained, so it may
|
||||
not work. It will be removed in future versions. Nonetheless, it is possible
|
||||
to find a different Python package (or write your own) to parse these file IDs
|
||||
and construct the necessary input file objects to send or download the media.
|
||||
|
||||
|
||||
Can I use Flask with the library?
|
||||
=================================
|
||||
|
||||
Yes, if you know what you are doing. However, you will probably have a
|
||||
lot of headaches to get threads and asyncio to work together. Instead,
|
||||
consider using `Quart <https://pgjones.gitlab.io/quart/>`_, an asyncio-based
|
||||
alternative to `Flask <flask.pocoo.org/>`_.
|
||||
|
||||
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, ...
|
||||
|
||||
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``
|
||||
file and run that, or use the normal ``python`` interpreter.
|
||||
|
||||
.. _logging: https://docs.python.org/3/library/logging.html
|
||||
.. _@SpamBot: https://t.me/SpamBot
|
||||
.. _issue 297: https://github.com/LonamiWebs/Telethon/issues/297
|
||||
.. _issue 3759: https://github.com/LonamiWebs/Telethon/issues/3759
|
||||
.. _quart_login.py: https://github.com/LonamiWebs/Telethon/tree/v1/telethon_examples#quart_loginpy
|
||||
|
|
@ -1,353 +0,0 @@
|
|||
=================
|
||||
Objects Reference
|
||||
=================
|
||||
|
||||
This is the quick reference for those objects returned by client methods
|
||||
or other useful modules that the library has to offer. They are kept in
|
||||
a separate page to help finding and discovering them.
|
||||
|
||||
Remember that this page only shows properties and methods,
|
||||
**not attributes**. Make sure to open the full documentation
|
||||
to find out about the attributes.
|
||||
|
||||
.. contents::
|
||||
|
||||
|
||||
ChatGetter
|
||||
==========
|
||||
|
||||
All events base `ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>`,
|
||||
and some of the objects below do too, so it's important to know its methods.
|
||||
|
||||
.. currentmodule:: telethon.tl.custom.chatgetter.ChatGetter
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
chat
|
||||
input_chat
|
||||
chat_id
|
||||
is_private
|
||||
is_group
|
||||
is_channel
|
||||
|
||||
get_chat
|
||||
get_input_chat
|
||||
|
||||
|
||||
SenderGetter
|
||||
============
|
||||
|
||||
Similar to `ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>`, a
|
||||
`SenderGetter <telethon.tl.custom.sendergetter.SenderGetter>` is the same,
|
||||
but it works for senders instead.
|
||||
|
||||
.. currentmodule:: telethon.tl.custom.sendergetter.SenderGetter
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
sender
|
||||
input_sender
|
||||
sender_id
|
||||
|
||||
get_sender
|
||||
get_input_sender
|
||||
|
||||
|
||||
Message
|
||||
=======
|
||||
|
||||
.. currentmodule:: telethon.tl.custom.message
|
||||
|
||||
The `Message` type is very important, mostly because we are working
|
||||
with a library for a *messaging* platform, so messages are widely used:
|
||||
in events, when fetching history, replies, etc.
|
||||
|
||||
It bases `ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>` and
|
||||
`SenderGetter <telethon.tl.custom.sendergetter.SenderGetter>`.
|
||||
|
||||
Properties
|
||||
----------
|
||||
|
||||
.. note::
|
||||
|
||||
We document *custom properties* here, not all the attributes of the
|
||||
`Message` (which is the information Telegram actually returns).
|
||||
|
||||
.. currentmodule:: telethon.tl.custom.message.Message
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
text
|
||||
raw_text
|
||||
is_reply
|
||||
forward
|
||||
buttons
|
||||
button_count
|
||||
file
|
||||
photo
|
||||
document
|
||||
web_preview
|
||||
audio
|
||||
voice
|
||||
video
|
||||
video_note
|
||||
gif
|
||||
sticker
|
||||
contact
|
||||
game
|
||||
geo
|
||||
invoice
|
||||
poll
|
||||
venue
|
||||
action_entities
|
||||
via_bot
|
||||
via_input_bot
|
||||
client
|
||||
|
||||
|
||||
Methods
|
||||
-------
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
respond
|
||||
reply
|
||||
forward_to
|
||||
edit
|
||||
delete
|
||||
get_reply_message
|
||||
click
|
||||
mark_read
|
||||
pin
|
||||
download_media
|
||||
get_entities_text
|
||||
get_buttons
|
||||
|
||||
|
||||
File
|
||||
====
|
||||
|
||||
The `File <telethon.tl.custom.file.File>` type is a wrapper object
|
||||
returned by `Message.file <telethon.tl.custom.message.Message.file>`,
|
||||
and you can use it to easily access a document's attributes, such as
|
||||
its name, bot-API style file ID, etc.
|
||||
|
||||
.. currentmodule:: telethon.tl.custom.file.File
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
id
|
||||
name
|
||||
ext
|
||||
mime_type
|
||||
width
|
||||
height
|
||||
size
|
||||
duration
|
||||
title
|
||||
performer
|
||||
emoji
|
||||
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
|
||||
over past "events" (deleted messages, edits, title changes, leaving members…)
|
||||
|
||||
These are all the properties you can find in it:
|
||||
|
||||
.. currentmodule:: telethon.tl.custom.adminlogevent.AdminLogEvent
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
id
|
||||
date
|
||||
user_id
|
||||
action
|
||||
old
|
||||
new
|
||||
changed_about
|
||||
changed_title
|
||||
changed_username
|
||||
changed_photo
|
||||
changed_sticker_set
|
||||
changed_message
|
||||
deleted_message
|
||||
changed_admin
|
||||
changed_restrictions
|
||||
changed_invites
|
||||
joined
|
||||
joined_invite
|
||||
left
|
||||
changed_hide_history
|
||||
changed_signatures
|
||||
changed_pin
|
||||
changed_default_banned_rights
|
||||
stopped_poll
|
||||
|
||||
|
||||
Button
|
||||
======
|
||||
|
||||
The `Button <telethon.tl.custom.button.Button>` class is used when you login
|
||||
as a bot account to send messages with reply markup, such as inline buttons
|
||||
or custom keyboards.
|
||||
|
||||
These are the static methods you can use to create instances of the markup:
|
||||
|
||||
.. currentmodule:: telethon.tl.custom.button.Button
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
inline
|
||||
switch_inline
|
||||
url
|
||||
auth
|
||||
text
|
||||
request_location
|
||||
request_phone
|
||||
request_poll
|
||||
clear
|
||||
force_reply
|
||||
|
||||
|
||||
InlineResult
|
||||
============
|
||||
|
||||
The `InlineResult <telethon.tl.custom.inlineresult.InlineResult>` object
|
||||
is returned inside a list by the `client.inline_query()
|
||||
<telethon.client.bots.BotMethods.inline_query>` method to make an inline
|
||||
query to a bot that supports being used in inline mode, such as
|
||||
`@like <https://t.me/like>`_.
|
||||
|
||||
Note that the list returned is in fact a *subclass* of a list called
|
||||
`InlineResults <telethon.tl.custom.inlineresults.InlineResults>`, which,
|
||||
in addition of being a list (iterator, indexed access, etc.), has extra
|
||||
attributes and methods.
|
||||
|
||||
These are the constants for the types, properties and methods you
|
||||
can find the individual results:
|
||||
|
||||
.. currentmodule:: telethon.tl.custom.inlineresult.InlineResult
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
ARTICLE
|
||||
PHOTO
|
||||
GIF
|
||||
VIDEO
|
||||
VIDEO_GIF
|
||||
AUDIO
|
||||
DOCUMENT
|
||||
LOCATION
|
||||
VENUE
|
||||
CONTACT
|
||||
GAME
|
||||
type
|
||||
message
|
||||
title
|
||||
description
|
||||
url
|
||||
photo
|
||||
document
|
||||
click
|
||||
download_media
|
||||
|
||||
|
||||
Dialog
|
||||
======
|
||||
|
||||
The `Dialog <telethon.tl.custom.dialog.Dialog>` object is returned when
|
||||
you call `client.iter_dialogs() <telethon.client.dialogs.DialogMethods.iter_dialogs>`.
|
||||
|
||||
.. currentmodule:: telethon.tl.custom.dialog.Dialog
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
send_message
|
||||
archive
|
||||
delete
|
||||
|
||||
|
||||
Draft
|
||||
======
|
||||
|
||||
The `Draft <telethon.tl.custom.draft.Draft>` object is returned when
|
||||
you call `client.iter_drafts() <telethon.client.dialogs.DialogMethods.iter_drafts>`.
|
||||
|
||||
.. currentmodule:: telethon.tl.custom.draft.Draft
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
entity
|
||||
input_entity
|
||||
get_entity
|
||||
get_input_entity
|
||||
text
|
||||
raw_text
|
||||
is_empty
|
||||
set_message
|
||||
send
|
||||
delete
|
||||
|
||||
|
||||
Utils
|
||||
=====
|
||||
|
||||
The `telethon.utils` module has plenty of methods that make using the
|
||||
library a lot easier. Only the interesting ones will be listed here.
|
||||
|
||||
.. currentmodule:: telethon.utils
|
||||
|
||||
.. autosummary::
|
||||
:nosignatures:
|
||||
|
||||
get_display_name
|
||||
get_extension
|
||||
get_inner_text
|
||||
get_peer_id
|
||||
resolve_id
|
||||
pack_bot_file_id
|
||||
resolve_bot_file_id
|
||||
resolve_invite_link
|
||||
|
|
@ -1,2 +1 @@
|
|||
./
|
||||
sphinx-rtd-theme~=1.3.0
|
||||
telethon
|
||||
|
|
@ -1,52 +1,37 @@
|
|||
.. _telethon-client:
|
||||
|
||||
==============
|
||||
TelegramClient
|
||||
==============
|
||||
|
||||
.. currentmodule:: telethon.client
|
||||
telethon\.client package
|
||||
========================
|
||||
|
||||
The `TelegramClient <telegramclient.TelegramClient>` aggregates several mixin
|
||||
classes to provide all the common functionality in a nice, Pythonic interface.
|
||||
Each mixin has its own methods, which you all can use.
|
||||
The `telethon.TelegramClient` aggregates several mixin classes to provide
|
||||
all the common functionality in a nice, Pythonic interface. Each mixin has
|
||||
its own methods, which you all can use.
|
||||
|
||||
**In short, to create a client you must run:**
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import asyncio
|
||||
from telethon import TelegramClient
|
||||
|
||||
client = TelegramClient(name, api_id, api_hash)
|
||||
|
||||
async def main():
|
||||
client = await TelegramClient(name, api_id, api_hash).start()
|
||||
# Now you can use all client methods listed below, like for example...
|
||||
await client.send_message('me', 'Hello to myself!')
|
||||
|
||||
with client:
|
||||
client.loop.run_until_complete(main())
|
||||
asyncio.get_event_loop().run_until_complete(main())
|
||||
|
||||
|
||||
You **don't** need to import these `AuthMethods`, `MessageMethods`, etc.
|
||||
Together they are the `TelegramClient <telegramclient.TelegramClient>` and
|
||||
you can access all of their methods.
|
||||
|
||||
See :ref:`client-ref` for a short summary.
|
||||
|
||||
.. automodule:: telethon.client.telegramclient
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
Together they are the `telethon.TelegramClient` and you can access all of
|
||||
their methods.
|
||||
|
||||
.. automodule:: telethon.client.telegrambaseclient
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. automodule:: telethon.client.account
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. automodule:: telethon.client.auth
|
||||
:members:
|
||||
:undoc-members:
|
||||
22
readthedocs/telethon.errors.rst
Normal file
22
readthedocs/telethon.errors.rst
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
.. _telethon-errors-package:
|
||||
|
||||
|
||||
telethon\.errors package
|
||||
========================
|
||||
|
||||
|
||||
telethon\.errors\.common module
|
||||
-------------------------------
|
||||
|
||||
.. automodule:: telethon.errors.common
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
telethon\.errors\.rpcbaseerrors module
|
||||
--------------------------------------
|
||||
|
||||
.. automodule:: telethon.errors.rpcbaseerrors
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
|
@ -1,12 +1,9 @@
|
|||
.. _telethon-events:
|
||||
.. _telethon-events-package:
|
||||
|
||||
=============
|
||||
Update Events
|
||||
=============
|
||||
telethon\.events package
|
||||
========================
|
||||
|
||||
.. currentmodule:: telethon.events
|
||||
|
||||
Every event (builder) subclasses `common.EventBuilder`,
|
||||
Every event (builder) subclasses `telethon.events.common.EventBuilder`,
|
||||
so all the methods in it can be used from any event builder/event instance.
|
||||
|
||||
.. automodule:: telethon.events.common
|
||||
|
|
@ -14,56 +11,62 @@ so all the methods in it can be used from any event builder/event instance.
|
|||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
.. automodule:: telethon.events.newmessage
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
.. automodule:: telethon.events.chataction
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
.. automodule:: telethon.events.userupdate
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
.. automodule:: telethon.events.messageedited
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
.. automodule:: telethon.events.messagedeleted
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
.. automodule:: telethon.events.messageread
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
.. automodule:: telethon.events.callbackquery
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
|
||||
.. automodule:: telethon.events.inlinequery
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. automodule:: telethon.events.album
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
.. automodule:: telethon.events.raw
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
.. automodule:: telethon.events
|
||||
:members:
|
||||
:undoc-members:
|
||||
27
readthedocs/telethon.extensions.rst
Normal file
27
readthedocs/telethon.extensions.rst
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
telethon\.extensions package
|
||||
============================
|
||||
|
||||
|
||||
telethon\.extensions\.binaryreader module
|
||||
-----------------------------------------
|
||||
|
||||
.. automodule:: telethon.extensions.binaryreader
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
telethon\.extensions\.markdown module
|
||||
-------------------------------------
|
||||
|
||||
.. automodule:: telethon.extensions.markdown
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
telethon\.extensions\.html module
|
||||
---------------------------------
|
||||
|
||||
.. automodule:: telethon.extensions.html
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
35
readthedocs/telethon.network.rst
Normal file
35
readthedocs/telethon.network.rst
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
telethon\.network package
|
||||
=========================
|
||||
|
||||
|
||||
telethon\.network\.connection module
|
||||
------------------------------------
|
||||
|
||||
.. automodule:: telethon.network.connection
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
telethon\.network\.mtprotoplainsender module
|
||||
------------------------------------------------
|
||||
|
||||
.. automodule:: telethon.network.mtprotoplainsender
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
telethon\.network\.mtprotosender module
|
||||
-----------------------------------------
|
||||
|
||||
.. automodule:: telethon.network.mtprotosender
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
telethon\.network\.authenticator module
|
||||
---------------------------------------
|
||||
|
||||
.. automodule:: telethon.network.authenticator
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
90
readthedocs/telethon.rst
Normal file
90
readthedocs/telethon.rst
Normal file
|
|
@ -0,0 +1,90 @@
|
|||
.. _telethon-package:
|
||||
|
||||
|
||||
telethon package
|
||||
================
|
||||
|
||||
|
||||
telethon\.client module
|
||||
-----------------------
|
||||
|
||||
.. toctree::
|
||||
|
||||
telethon.client
|
||||
|
||||
.. automodule:: telethon.client
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
telethon\.utils module
|
||||
----------------------
|
||||
|
||||
.. automodule:: telethon.utils
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
telethon\.helpers module
|
||||
------------------------
|
||||
|
||||
.. automodule:: telethon.helpers
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
|
||||
telethon\.events package
|
||||
------------------------
|
||||
|
||||
.. toctree::
|
||||
|
||||
telethon.events
|
||||
|
||||
|
||||
telethon\.sessions module
|
||||
-------------------------
|
||||
|
||||
.. automodule:: telethon.sessions
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
telethon\.errors package
|
||||
------------------------
|
||||
|
||||
.. toctree::
|
||||
|
||||
telethon.errors
|
||||
|
||||
telethon\.extensions package
|
||||
----------------------------
|
||||
|
||||
.. toctree::
|
||||
|
||||
telethon.extensions
|
||||
|
||||
telethon\.network package
|
||||
-------------------------
|
||||
|
||||
.. toctree::
|
||||
|
||||
telethon.network
|
||||
|
||||
telethon\.tl package
|
||||
--------------------
|
||||
|
||||
.. toctree::
|
||||
|
||||
telethon.tl
|
||||
|
||||
|
||||
Module contents
|
||||
---------------
|
||||
|
||||
.. automodule:: telethon
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
99
readthedocs/telethon.tl.custom.rst
Normal file
99
readthedocs/telethon.tl.custom.rst
Normal file
|
|
@ -0,0 +1,99 @@
|
|||
telethon\.tl\.custom package
|
||||
============================
|
||||
|
||||
|
||||
telethon\.tl\.custom\.draft module
|
||||
----------------------------------
|
||||
|
||||
.. automodule:: telethon.tl.custom.draft
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
telethon\.tl\.custom\.dialog module
|
||||
-----------------------------------
|
||||
|
||||
.. automodule:: telethon.tl.custom.dialog
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
telethon\.tl\.custom\.message module
|
||||
------------------------------------
|
||||
|
||||
.. automodule:: telethon.tl.custom.message
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
telethon\.tl\.custom\.messagebutton module
|
||||
------------------------------------------
|
||||
|
||||
.. automodule:: telethon.tl.custom.messagebutton
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
telethon\.tl\.custom\.forward module
|
||||
------------------------------------
|
||||
|
||||
.. automodule:: telethon.tl.custom.forward
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
telethon\.tl\.custom\.button module
|
||||
-----------------------------------
|
||||
|
||||
.. automodule:: telethon.tl.custom.button
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
telethon\.tl\.custom\.inlinebuilder module
|
||||
------------------------------------------
|
||||
|
||||
.. automodule:: telethon.tl.custom.inlinebuilder
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
telethon\.tl\.custom\.inlineresult module
|
||||
-----------------------------------------
|
||||
|
||||
.. automodule:: telethon.tl.custom.inlineresult
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
telethon\.tl\.custom\.inlineresults module
|
||||
------------------------------------------
|
||||
|
||||
.. automodule:: telethon.tl.custom.inlineresults
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
telethon\.tl\.custom\.chatgetter module
|
||||
---------------------------------------
|
||||
|
||||
.. automodule:: telethon.tl.custom.chatgetter
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
telethon\.tl\.custom\.sendergetter module
|
||||
-----------------------------------------
|
||||
|
||||
.. automodule:: telethon.tl.custom.sendergetter
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
telethon\.tl\.custom\.conversation module
|
||||
-----------------------------------------
|
||||
|
||||
.. automodule:: telethon.tl.custom.conversation
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
16
readthedocs/telethon.tl.rst
Normal file
16
readthedocs/telethon.tl.rst
Normal file
|
|
@ -0,0 +1,16 @@
|
|||
telethon\.tl\.custom package
|
||||
============================
|
||||
|
||||
|
||||
.. toctree::
|
||||
|
||||
telethon.tl.custom
|
||||
|
||||
|
||||
telethon\.tl\.tlobject module
|
||||
-----------------------------
|
||||
|
||||
.. automodule:: telethon.tl.tlobject
|
||||
:members:
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
|
@ -1,2 +1,3 @@
|
|||
pyaes
|
||||
rsa
|
||||
async_generator
|
||||
|
|
|
|||
153
setup.py
153
setup.py
|
|
@ -15,75 +15,66 @@ import json
|
|||
import os
|
||||
import re
|
||||
import shutil
|
||||
import sys
|
||||
import urllib.request
|
||||
from pathlib import Path
|
||||
from subprocess import run
|
||||
from sys import argv
|
||||
|
||||
from setuptools import find_packages, setup
|
||||
|
||||
# Needed since we're importing local files
|
||||
sys.path.insert(0, os.path.dirname(__file__))
|
||||
|
||||
class TempWorkDir:
|
||||
"""Switches the working directory to be the one on which this file lives,
|
||||
while within the 'with' block.
|
||||
"""
|
||||
def __init__(self, new=None):
|
||||
def __init__(self):
|
||||
self.original = None
|
||||
self.new = new or str(Path(__file__).parent.resolve())
|
||||
|
||||
def __enter__(self):
|
||||
# os.chdir does not work with Path in Python 3.5.x
|
||||
self.original = str(Path('.').resolve())
|
||||
os.makedirs(self.new, exist_ok=True)
|
||||
os.chdir(self.new)
|
||||
self.original = os.path.abspath(os.path.curdir)
|
||||
os.chdir(os.path.abspath(os.path.dirname(__file__)))
|
||||
return self
|
||||
|
||||
def __exit__(self, *args):
|
||||
os.chdir(self.original)
|
||||
|
||||
|
||||
API_REF_URL = 'https://tl.telethon.dev/'
|
||||
GENERATOR_DIR = 'telethon_generator'
|
||||
LIBRARY_DIR = 'telethon'
|
||||
|
||||
GENERATOR_DIR = Path('telethon_generator')
|
||||
LIBRARY_DIR = Path('telethon')
|
||||
ERRORS_IN = os.path.join(GENERATOR_DIR, 'data', 'errors.csv')
|
||||
ERRORS_OUT = os.path.join(LIBRARY_DIR, 'errors', 'rpcerrorlist.py')
|
||||
|
||||
ERRORS_IN = GENERATOR_DIR / 'data/errors.csv'
|
||||
ERRORS_OUT = LIBRARY_DIR / 'errors/rpcerrorlist.py'
|
||||
METHODS_IN = os.path.join(GENERATOR_DIR, 'data', 'methods.csv')
|
||||
|
||||
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'
|
||||
TLOBJECT_IN_CORE_TL = os.path.join(GENERATOR_DIR, 'data', 'mtproto_api.tl')
|
||||
TLOBJECT_IN_TL = os.path.join(GENERATOR_DIR, 'data', 'telegram_api.tl')
|
||||
TLOBJECT_OUT = os.path.join(LIBRARY_DIR, 'tl')
|
||||
IMPORT_DEPTH = 2
|
||||
|
||||
DOCS_IN_RES = GENERATOR_DIR / 'data/html'
|
||||
DOCS_OUT = Path('docs')
|
||||
DOCS_IN_RES = os.path.join(GENERATOR_DIR, 'data', 'html')
|
||||
DOCS_OUT = 'docs'
|
||||
|
||||
|
||||
def generate(which, action='gen'):
|
||||
def generate(which):
|
||||
from telethon_generator.parsers import\
|
||||
parse_errors, parse_methods, parse_tl, find_layer
|
||||
|
||||
from telethon_generator.generators import\
|
||||
generate_errors, generate_tlobjects, generate_docs, clean_tlobjects
|
||||
|
||||
layer = next(filter(None, map(find_layer, TLOBJECT_IN_TLS)))
|
||||
layer = find_layer(TLOBJECT_IN_TL)
|
||||
errors = list(parse_errors(ERRORS_IN))
|
||||
methods = list(parse_methods(METHODS_IN, FRIENDLY_IN, {e.str_code: e for e in errors}))
|
||||
methods = list(parse_methods(METHODS_IN, {e.str_code: e for e in errors}))
|
||||
|
||||
tlobjects = list(itertools.chain(*(
|
||||
parse_tl(file, layer, methods) for file in TLOBJECT_IN_TLS)))
|
||||
tlobjects = list(itertools.chain(
|
||||
parse_tl(TLOBJECT_IN_CORE_TL, layer, methods),
|
||||
parse_tl(TLOBJECT_IN_TL, layer, methods)))
|
||||
|
||||
if not which:
|
||||
which.extend(('tl', 'errors'))
|
||||
|
||||
clean = action == 'clean'
|
||||
clean = 'clean' in which
|
||||
action = 'Cleaning' if clean else 'Generating'
|
||||
if clean:
|
||||
which.remove('clean')
|
||||
|
||||
if 'all' in which:
|
||||
which.remove('all')
|
||||
|
|
@ -103,105 +94,84 @@ def generate(which, action='gen'):
|
|||
which.remove('errors')
|
||||
print(action, 'RPCErrors...')
|
||||
if clean:
|
||||
if ERRORS_OUT.is_file():
|
||||
ERRORS_OUT.unlink()
|
||||
if os.path.isfile(ERRORS_OUT):
|
||||
os.remove(ERRORS_OUT)
|
||||
else:
|
||||
with ERRORS_OUT.open('w') as file:
|
||||
with open(ERRORS_OUT, 'w', encoding='utf-8') as file:
|
||||
generate_errors(errors, file)
|
||||
|
||||
if 'docs' in which:
|
||||
which.remove('docs')
|
||||
print(action, 'documentation...')
|
||||
if clean:
|
||||
if DOCS_OUT.is_dir():
|
||||
shutil.rmtree(str(DOCS_OUT))
|
||||
if os.path.isdir(DOCS_OUT):
|
||||
shutil.rmtree(DOCS_OUT)
|
||||
else:
|
||||
in_path = DOCS_IN_RES.resolve()
|
||||
with TempWorkDir(DOCS_OUT):
|
||||
generate_docs(tlobjects, methods, layer, in_path)
|
||||
generate_docs(tlobjects, methods, layer, DOCS_IN_RES, DOCS_OUT)
|
||||
|
||||
if 'json' in which:
|
||||
which.remove('json')
|
||||
print(action, 'JSON schema...')
|
||||
json_files = [x.with_suffix('.json') for x in TLOBJECT_IN_TLS]
|
||||
mtproto = 'mtproto_api.json'
|
||||
telegram = 'telegram_api.json'
|
||||
if clean:
|
||||
for file in json_files:
|
||||
if file.is_file():
|
||||
file.unlink()
|
||||
for x in (mtproto, telegram):
|
||||
if os.path.isfile(x):
|
||||
os.remove(x)
|
||||
else:
|
||||
def gen_json(fin, fout):
|
||||
meths = []
|
||||
methods = []
|
||||
constructors = []
|
||||
for tl in parse_tl(fin, layer):
|
||||
if tl.is_function:
|
||||
meths.append(tl.to_dict())
|
||||
methods.append(tl.to_dict())
|
||||
else:
|
||||
constructors.append(tl.to_dict())
|
||||
what = {'constructors': constructors, 'methods': meths}
|
||||
what = {'constructors': constructors, 'methods': methods}
|
||||
with open(fout, 'w') as f:
|
||||
json.dump(what, f, indent=2)
|
||||
|
||||
for fs in zip(TLOBJECT_IN_TLS, json_files):
|
||||
gen_json(*fs)
|
||||
gen_json(TLOBJECT_IN_CORE_TL, mtproto)
|
||||
gen_json(TLOBJECT_IN_TL, telegram)
|
||||
|
||||
if which:
|
||||
print(
|
||||
'The following items were not understood:', which,
|
||||
'\n Consider using only "tl", "errors" and/or "docs".'
|
||||
'\n Using only "clean" will clean them. "all" to act on all.'
|
||||
'\n For instance "gen tl errors".'
|
||||
)
|
||||
print('The following items were not understood:', which)
|
||||
print(' Consider using only "tl", "errors" and/or "docs".')
|
||||
print(' Using only "clean" will clean them. "all" to act on all.')
|
||||
print(' For instance "gen tl errors".')
|
||||
|
||||
|
||||
def main(argv):
|
||||
if len(argv) >= 2 and argv[1] in ('gen', 'clean'):
|
||||
generate(argv[2:], argv[1])
|
||||
def main():
|
||||
if len(argv) >= 2 and argv[1] == 'gen':
|
||||
generate(argv[2:])
|
||||
|
||||
elif len(argv) >= 2 and argv[1] == 'pypi':
|
||||
# Make sure tl.telethon.dev is up-to-date first
|
||||
with urllib.request.urlopen(API_REF_URL) as resp:
|
||||
html = resp.read()
|
||||
m = re.search(br'layer\s+(\d+)', html)
|
||||
if not m:
|
||||
print('Failed to check that the API reference is up to date:', API_REF_URL)
|
||||
return
|
||||
|
||||
from telethon_generator.parsers import find_layer
|
||||
layer = next(filter(None, map(find_layer, TLOBJECT_IN_TLS)))
|
||||
published_layer = int(m[1])
|
||||
if published_layer != layer:
|
||||
print('Published layer', published_layer, 'does not match current layer', layer, '.')
|
||||
print('Make sure to update the API reference site first:', API_REF_URL)
|
||||
return
|
||||
|
||||
# (Re)generate the code to make sure we don't push without it
|
||||
generate(['tl', 'errors'])
|
||||
|
||||
# Try importing the telethon module to assert it has no errors
|
||||
try:
|
||||
import telethon
|
||||
except Exception as e:
|
||||
except:
|
||||
print('Packaging for PyPi aborted, importing the module failed.')
|
||||
print(e)
|
||||
return
|
||||
|
||||
remove_dirs = ['__pycache__', 'build', 'dist', 'Telethon.egg-info']
|
||||
for root, _dirs, _files in os.walk(LIBRARY_DIR, topdown=False):
|
||||
# setuptools is including __pycache__ for some reason (#1605)
|
||||
if root.endswith('/__pycache__'):
|
||||
remove_dirs.append(root)
|
||||
for x in remove_dirs:
|
||||
shutil.rmtree(x, ignore_errors=True)
|
||||
# Need python3.5 or higher, but Telethon is supposed to support 3.x
|
||||
# Place it here since noone should be running ./setup.py pypi anyway
|
||||
from subprocess import run
|
||||
from shutil import rmtree
|
||||
|
||||
for x in ('build', 'dist', 'Telethon.egg-info'):
|
||||
rmtree(x, ignore_errors=True)
|
||||
run('python3 setup.py sdist', shell=True)
|
||||
run('python3 setup.py bdist_wheel', shell=True)
|
||||
run('twine upload dist/*', shell=True)
|
||||
for x in ('build', 'dist', 'Telethon.egg-info'):
|
||||
shutil.rmtree(x, ignore_errors=True)
|
||||
rmtree(x, ignore_errors=True)
|
||||
|
||||
else:
|
||||
# e.g. install from GitHub
|
||||
if GENERATOR_DIR.is_dir():
|
||||
if os.path.isdir(GENERATOR_DIR):
|
||||
generate(['tl', 'errors'])
|
||||
|
||||
# Get the long description from the README file
|
||||
|
|
@ -244,15 +214,14 @@ def main(argv):
|
|||
|
||||
'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.6'
|
||||
],
|
||||
keywords='telegram api chat client library messaging mtproto',
|
||||
packages=find_packages(exclude=[
|
||||
'telethon_*', 'tests*'
|
||||
'telethon_*', 'run_tests.py', 'try_telethon.py'
|
||||
]),
|
||||
install_requires=['pyaes', 'rsa'],
|
||||
install_requires=['pyaes', 'rsa',
|
||||
'async_generator'],
|
||||
extras_require={
|
||||
'cryptg': ['cryptg']
|
||||
}
|
||||
|
|
@ -260,5 +229,5 @@ def main(argv):
|
|||
|
||||
|
||||
if __name__ == '__main__':
|
||||
with TempWorkDir():
|
||||
main(sys.argv)
|
||||
with TempWorkDir(): # Could just use a try/finally but this is + reusable
|
||||
main()
|
||||
|
|
|
|||
|
|
@ -1,13 +1,12 @@
|
|||
import logging
|
||||
from .client.telegramclient import TelegramClient
|
||||
from .network import connection
|
||||
from .tl.custom import Button
|
||||
from .tl import patched as _ # import for its side-effects
|
||||
from . import version, events, utils, errors, types, functions, custom
|
||||
from .tl import types, functions, custom
|
||||
from . import version, events, utils, errors
|
||||
|
||||
|
||||
__version__ = version.__version__
|
||||
logging.getLogger(__name__).addHandler(logging.NullHandler())
|
||||
|
||||
__all__ = [
|
||||
'TelegramClient', 'Button',
|
||||
'types', 'functions', 'custom', 'errors',
|
||||
'events', 'utils', 'connection'
|
||||
]
|
||||
__all__ = ['TelegramClient', 'types', 'functions', 'custom',
|
||||
'events', 'utils', 'errors']
|
||||
|
|
|
|||
|
|
@ -1,3 +0,0 @@
|
|||
from .entitycache import EntityCache
|
||||
from .messagebox import MessageBox, GapError, PrematureEndReason
|
||||
from .session import SessionState, ChannelState, Entity, EntityType
|
||||
|
|
@ -1,62 +0,0 @@
|
|||
from .session import EntityType, Entity
|
||||
|
||||
|
||||
_sentinel = object()
|
||||
|
||||
|
||||
class EntityCache:
|
||||
def __init__(
|
||||
self,
|
||||
hash_map: dict = _sentinel,
|
||||
self_id: int = None,
|
||||
self_bot: bool = None
|
||||
):
|
||||
self.hash_map = {} if hash_map is _sentinel else hash_map
|
||||
self.self_id = self_id
|
||||
self.self_bot = self_bot
|
||||
|
||||
def set_self_user(self, id, bot, hash):
|
||||
self.self_id = id
|
||||
self.self_bot = bot
|
||||
if hash:
|
||||
self.hash_map[id] = (hash, EntityType.BOT if bot else EntityType.USER)
|
||||
|
||||
def get(self, id):
|
||||
try:
|
||||
hash, ty = self.hash_map[id]
|
||||
return Entity(ty, id, hash)
|
||||
except KeyError:
|
||||
return None
|
||||
|
||||
def extend(self, users, chats):
|
||||
# See https://core.telegram.org/api/min for "issues" with "min constructors".
|
||||
self.hash_map.update(
|
||||
(u.id, (
|
||||
u.access_hash,
|
||||
EntityType.BOT if u.bot else EntityType.USER,
|
||||
))
|
||||
for u in users
|
||||
if getattr(u, 'access_hash', None) and not u.min
|
||||
)
|
||||
self.hash_map.update(
|
||||
(c.id, (
|
||||
c.access_hash,
|
||||
EntityType.MEGAGROUP if c.megagroup else (
|
||||
EntityType.GIGAGROUP if getattr(c, 'gigagroup', None) else EntityType.CHANNEL
|
||||
),
|
||||
))
|
||||
for c in chats
|
||||
if getattr(c, 'access_hash', None) and not getattr(c, 'min', None)
|
||||
)
|
||||
|
||||
def get_all_entities(self):
|
||||
return [Entity(ty, id, hash) for id, (hash, ty) in self.hash_map.items()]
|
||||
|
||||
def put(self, entity):
|
||||
self.hash_map[entity.id] = (entity.hash, entity.ty)
|
||||
|
||||
def retain(self, filter):
|
||||
self.hash_map = {k: v for k, v in self.hash_map.items() if filter(k)}
|
||||
|
||||
def __len__(self):
|
||||
return len(self.hash_map)
|
||||
|
|
@ -1,833 +0,0 @@
|
|||
"""
|
||||
This module deals with correct handling of updates, including gaps, and knowing when the code
|
||||
should "get difference" (the set of updates that the client should know by now minus the set
|
||||
of updates that it actually knows).
|
||||
|
||||
Each chat has its own [`Entry`] in the [`MessageBox`] (this `struct` is the "entry point").
|
||||
At any given time, the message box may be either getting difference for them (entry is in
|
||||
[`MessageBox::getting_diff_for`]) or not. If not getting difference, a possible gap may be
|
||||
found for the updates (entry is in [`MessageBox::possible_gaps`]). Otherwise, the entry is
|
||||
on its happy path.
|
||||
|
||||
Gaps are cleared when they are either resolved on their own (by waiting for a short time)
|
||||
or because we got the difference for the corresponding entry.
|
||||
|
||||
While there are entries for which their difference must be fetched,
|
||||
[`MessageBox::check_deadlines`] will always return [`Instant::now`], since "now" is the time
|
||||
to get the difference.
|
||||
"""
|
||||
import asyncio
|
||||
import datetime
|
||||
import time
|
||||
import logging
|
||||
from enum import Enum
|
||||
from .session import SessionState, ChannelState
|
||||
from ..tl import types as tl, functions as fn
|
||||
from ..helpers import get_running_loop
|
||||
|
||||
|
||||
# Telegram sends `seq` equal to `0` when "it doesn't matter", so we use that value too.
|
||||
NO_SEQ = 0
|
||||
|
||||
# See https://core.telegram.org/method/updates.getChannelDifference.
|
||||
BOT_CHANNEL_DIFF_LIMIT = 100000
|
||||
USER_CHANNEL_DIFF_LIMIT = 100
|
||||
|
||||
# > It may be useful to wait up to 0.5 seconds
|
||||
POSSIBLE_GAP_TIMEOUT = 0.5
|
||||
|
||||
# After how long without updates the client will "timeout".
|
||||
#
|
||||
# When this timeout occurs, the client will attempt to fetch updates by itself, ignoring all the
|
||||
# updates that arrive in the meantime. After all updates are fetched when this happens, the
|
||||
# client will resume normal operation, and the timeout will reset.
|
||||
#
|
||||
# Documentation recommends 15 minutes without updates (https://core.telegram.org/api/updates).
|
||||
NO_UPDATES_TIMEOUT = 15 * 60
|
||||
|
||||
# object() but with a tag to make it easier to debug
|
||||
class Sentinel:
|
||||
__slots__ = ('tag',)
|
||||
|
||||
def __init__(self, tag=None):
|
||||
self.tag = tag or '_'
|
||||
|
||||
def __repr__(self):
|
||||
return self.tag
|
||||
|
||||
# Entry "enum".
|
||||
# Account-wide `pts` includes private conversations (one-to-one) and small group chats.
|
||||
ENTRY_ACCOUNT = Sentinel('ACCOUNT')
|
||||
# Account-wide `qts` includes only "secret" one-to-one chats.
|
||||
ENTRY_SECRET = Sentinel('SECRET')
|
||||
# Integers will be Channel-specific `pts`, and includes "megagroup", "broadcast" and "supergroup" channels.
|
||||
|
||||
# Python's logging doesn't define a TRACE level. Pick halfway between DEBUG and NOTSET.
|
||||
# We don't define a name for this as libraries shouldn't do that though.
|
||||
LOG_LEVEL_TRACE = (logging.DEBUG - logging.NOTSET) // 2
|
||||
|
||||
_sentinel = Sentinel()
|
||||
|
||||
def next_updates_deadline():
|
||||
return get_running_loop().time() + NO_UPDATES_TIMEOUT
|
||||
|
||||
def epoch():
|
||||
return datetime.datetime(*time.gmtime(0)[:6]).replace(tzinfo=datetime.timezone.utc)
|
||||
|
||||
class GapError(ValueError):
|
||||
def __repr__(self):
|
||||
return 'GapError()'
|
||||
|
||||
|
||||
class PrematureEndReason(Enum):
|
||||
TEMPORARY_SERVER_ISSUES = 'tmp'
|
||||
BANNED = 'ban'
|
||||
|
||||
|
||||
# Represents the information needed to correctly handle a specific `tl::enums::Update`.
|
||||
class PtsInfo:
|
||||
__slots__ = ('pts', 'pts_count', 'entry')
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
pts: int,
|
||||
pts_count: int,
|
||||
entry: object
|
||||
):
|
||||
self.pts = pts
|
||||
self.pts_count = pts_count
|
||||
self.entry = entry
|
||||
|
||||
@classmethod
|
||||
def from_update(cls, update):
|
||||
pts = getattr(update, 'pts', None)
|
||||
if pts:
|
||||
pts_count = getattr(update, 'pts_count', None) or 0
|
||||
try:
|
||||
entry = update.message.peer_id.channel_id
|
||||
except AttributeError:
|
||||
entry = getattr(update, 'channel_id', None) or ENTRY_ACCOUNT
|
||||
return cls(pts=pts, pts_count=pts_count, entry=entry)
|
||||
|
||||
qts = getattr(update, 'qts', None)
|
||||
if qts:
|
||||
return cls(pts=qts, pts_count=1, entry=ENTRY_SECRET)
|
||||
|
||||
return None
|
||||
|
||||
def __repr__(self):
|
||||
return f'PtsInfo(pts={self.pts}, pts_count={self.pts_count}, entry={self.entry})'
|
||||
|
||||
|
||||
# The state of a particular entry in the message box.
|
||||
class State:
|
||||
__slots__ = ('pts', 'deadline')
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
# Current local persistent timestamp.
|
||||
pts: int,
|
||||
# Next instant when we would get the update difference if no updates arrived before then.
|
||||
deadline: float
|
||||
):
|
||||
self.pts = pts
|
||||
self.deadline = deadline
|
||||
|
||||
def __repr__(self):
|
||||
return f'State(pts={self.pts}, deadline={self.deadline})'
|
||||
|
||||
|
||||
# > ### Recovering gaps
|
||||
# > […] Manually obtaining updates is also required in the following situations:
|
||||
# > • Loss of sync: a gap was found in `seq` / `pts` / `qts` (as described above).
|
||||
# > It may be useful to wait up to 0.5 seconds in this situation and abort the sync in case a new update
|
||||
# > arrives, that fills the gap.
|
||||
#
|
||||
# This is really easy to trigger by spamming messages in a channel (with as little as 3 members works), because
|
||||
# the updates produced by the RPC request take a while to arrive (whereas the read update comes faster alone).
|
||||
class PossibleGap:
|
||||
__slots__ = ('deadline', 'updates')
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
deadline: float,
|
||||
# Pending updates (those with a larger PTS, producing the gap which may later be filled).
|
||||
updates: list # of updates
|
||||
):
|
||||
self.deadline = deadline
|
||||
self.updates = updates
|
||||
|
||||
def __repr__(self):
|
||||
return f'PossibleGap(deadline={self.deadline}, update_count={len(self.updates)})'
|
||||
|
||||
|
||||
# Represents a "message box" (event `pts` for a specific entry).
|
||||
#
|
||||
# See https://core.telegram.org/api/updates#message-related-event-sequences.
|
||||
class MessageBox:
|
||||
__slots__ = ('_log', 'map', 'date', 'seq', 'next_deadline', 'possible_gaps', 'getting_diff_for')
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
log,
|
||||
# Map each entry to their current state.
|
||||
map: dict = _sentinel, # entry -> state
|
||||
|
||||
# Additional fields beyond PTS needed by `ENTRY_ACCOUNT`.
|
||||
date: datetime.datetime = epoch() + datetime.timedelta(seconds=1),
|
||||
seq: int = NO_SEQ,
|
||||
|
||||
# Holds the entry with the closest deadline (optimization to avoid recalculating the minimum deadline).
|
||||
next_deadline: object = None, # entry
|
||||
|
||||
# Which entries have a gap and may soon trigger a need to get difference.
|
||||
#
|
||||
# If a gap is found, stores the required information to resolve it (when should it timeout and what updates
|
||||
# should be held in case the gap is resolved on its own).
|
||||
#
|
||||
# Not stored directly in `map` as an optimization (else we would need another way of knowing which entries have
|
||||
# a gap in them).
|
||||
possible_gaps: dict = _sentinel, # entry -> possiblegap
|
||||
|
||||
# For which entries are we currently getting difference.
|
||||
getting_diff_for: set = _sentinel, # entry
|
||||
):
|
||||
self._log = log
|
||||
self.map = {} if map is _sentinel else map
|
||||
self.date = date
|
||||
self.seq = seq
|
||||
self.next_deadline = next_deadline
|
||||
self.possible_gaps = {} if possible_gaps is _sentinel else possible_gaps
|
||||
self.getting_diff_for = set() if getting_diff_for is _sentinel else getting_diff_for
|
||||
|
||||
if __debug__:
|
||||
self._trace('MessageBox initialized')
|
||||
|
||||
def _trace(self, msg, *args, **kwargs):
|
||||
# Calls to trace can't really be removed beforehand without some dark magic.
|
||||
# So every call to trace is prefixed with `if __debug__`` instead, to remove
|
||||
# it when using `python -O`. Probably unnecessary, but it's nice to avoid
|
||||
# paying the cost for something that is not used.
|
||||
self._log.log(LOG_LEVEL_TRACE, 'Current MessageBox state: seq = %r, date = %s, map = %r',
|
||||
self.seq, self.date.isoformat(), self.map)
|
||||
self._log.log(LOG_LEVEL_TRACE, msg, *args, **kwargs)
|
||||
|
||||
# region Creation, querying, and setting base state.
|
||||
|
||||
def load(self, session_state, channel_states):
|
||||
"""
|
||||
Create a [`MessageBox`] from a previously known update state.
|
||||
"""
|
||||
if __debug__:
|
||||
self._trace('Loading MessageBox with session_state = %r, channel_states = %r', session_state, channel_states)
|
||||
|
||||
deadline = next_updates_deadline()
|
||||
|
||||
self.map.clear()
|
||||
if session_state.pts != NO_SEQ:
|
||||
self.map[ENTRY_ACCOUNT] = State(pts=session_state.pts, deadline=deadline)
|
||||
if session_state.qts != NO_SEQ:
|
||||
self.map[ENTRY_SECRET] = State(pts=session_state.qts, deadline=deadline)
|
||||
self.map.update((s.channel_id, State(pts=s.pts, deadline=deadline)) for s in channel_states)
|
||||
|
||||
self.date = datetime.datetime.fromtimestamp(session_state.date, tz=datetime.timezone.utc)
|
||||
self.seq = session_state.seq
|
||||
self.next_deadline = ENTRY_ACCOUNT
|
||||
|
||||
def session_state(self):
|
||||
"""
|
||||
Return the current state.
|
||||
|
||||
This should be used for persisting the state.
|
||||
"""
|
||||
return dict(
|
||||
pts=self.map[ENTRY_ACCOUNT].pts if ENTRY_ACCOUNT in self.map else NO_SEQ,
|
||||
qts=self.map[ENTRY_SECRET].pts if ENTRY_SECRET in self.map else NO_SEQ,
|
||||
date=self.date,
|
||||
seq=self.seq,
|
||||
), {id: state.pts for id, state in self.map.items() if isinstance(id, int)}
|
||||
|
||||
def is_empty(self) -> bool:
|
||||
"""
|
||||
Return true if the message box is empty and has no state yet.
|
||||
"""
|
||||
return ENTRY_ACCOUNT not in self.map
|
||||
|
||||
def check_deadlines(self):
|
||||
"""
|
||||
Return the next deadline when receiving updates should timeout.
|
||||
|
||||
If a deadline expired, the corresponding entries will be marked as needing to get its difference.
|
||||
While there are entries pending of getting their difference, this method returns the current instant.
|
||||
"""
|
||||
now = get_running_loop().time()
|
||||
|
||||
if self.getting_diff_for:
|
||||
return now
|
||||
|
||||
deadline = next_updates_deadline()
|
||||
|
||||
# Most of the time there will be zero or one gap in flight so finding the minimum is cheap.
|
||||
if self.possible_gaps:
|
||||
deadline = min(deadline, *(gap.deadline for gap in self.possible_gaps.values()))
|
||||
elif self.next_deadline in self.map:
|
||||
deadline = min(deadline, self.map[self.next_deadline].deadline)
|
||||
|
||||
# asyncio's loop time precision only seems to be about 3 decimal places, so it's possible that
|
||||
# we find the same number again on repeated calls. Without the "or equal" part we would log the
|
||||
# timeout for updates several times (it also makes sense to get difference if now is the deadline).
|
||||
if now >= deadline:
|
||||
# Check all expired entries and add them to the list that needs getting difference.
|
||||
self.getting_diff_for.update(entry for entry, gap in self.possible_gaps.items() if now >= gap.deadline)
|
||||
self.getting_diff_for.update(entry for entry, state in self.map.items() if now >= state.deadline)
|
||||
|
||||
if __debug__:
|
||||
self._trace('Deadlines met, now getting diff for %r', self.getting_diff_for)
|
||||
|
||||
# When extending `getting_diff_for`, it's important to have the moral equivalent of
|
||||
# `begin_get_diff` (that is, clear possible gaps if we're now getting difference).
|
||||
for entry in self.getting_diff_for:
|
||||
self.possible_gaps.pop(entry, None)
|
||||
|
||||
return deadline
|
||||
|
||||
# Reset the deadline for the periods without updates for the given entries.
|
||||
#
|
||||
# It also updates the next deadline time to reflect the new closest deadline.
|
||||
def reset_deadlines(self, entries, deadline):
|
||||
if not entries:
|
||||
return
|
||||
for entry in entries:
|
||||
if entry not in self.map:
|
||||
raise RuntimeError('Called reset_deadline on an entry for which we do not have state')
|
||||
self.map[entry].deadline = deadline
|
||||
|
||||
if self.next_deadline in entries:
|
||||
# If the updated deadline was the closest one, recalculate the new minimum.
|
||||
self.next_deadline = min(self.map.items(), key=lambda entry_state: entry_state[1].deadline)[0]
|
||||
elif self.next_deadline in self.map and deadline < self.map[self.next_deadline].deadline:
|
||||
# If the updated deadline is smaller than the next deadline, change the next deadline to be the new one.
|
||||
# Any entry will do, so the one from the last iteration is fine.
|
||||
self.next_deadline = entry
|
||||
# else an unrelated deadline was updated, so the closest one remains unchanged.
|
||||
|
||||
# Convenience to reset a channel's deadline, with optional timeout.
|
||||
def reset_channel_deadline(self, channel_id, timeout):
|
||||
self.reset_deadlines({channel_id}, get_running_loop().time() + (timeout or NO_UPDATES_TIMEOUT))
|
||||
|
||||
# Sets the update state.
|
||||
#
|
||||
# Should be called right after login if [`MessageBox::new`] was used, otherwise undesirable
|
||||
# updates will be fetched.
|
||||
def set_state(self, state, reset=True):
|
||||
if __debug__:
|
||||
self._trace('Setting state %s', state)
|
||||
|
||||
deadline = next_updates_deadline()
|
||||
|
||||
if state.pts != NO_SEQ or not reset:
|
||||
self.map[ENTRY_ACCOUNT] = State(pts=state.pts, deadline=deadline)
|
||||
else:
|
||||
self.map.pop(ENTRY_ACCOUNT, None)
|
||||
|
||||
# Telegram seems to use the `qts` for bot accounts, but while applying difference,
|
||||
# it might be reset back to 0. See issue #3873 for more details.
|
||||
#
|
||||
# During login, a value of zero would mean the `pts` is unknown,
|
||||
# so the map shouldn't contain that entry.
|
||||
# But while applying difference, if the value is zero, it (probably)
|
||||
# truly means that's what should be used (hence the `reset` flag).
|
||||
if state.qts != NO_SEQ or not reset:
|
||||
self.map[ENTRY_SECRET] = State(pts=state.qts, deadline=deadline)
|
||||
else:
|
||||
self.map.pop(ENTRY_SECRET, None)
|
||||
|
||||
self.date = state.date
|
||||
self.seq = state.seq
|
||||
|
||||
# Like [`MessageBox::set_state`], but for channels. Useful when getting dialogs.
|
||||
#
|
||||
# The update state will only be updated if no entry was known previously.
|
||||
def try_set_channel_state(self, id, pts):
|
||||
if __debug__:
|
||||
self._trace('Trying to set channel state for %r: %r', id, pts)
|
||||
|
||||
if id not in self.map:
|
||||
self.map[id] = State(pts=pts, deadline=next_updates_deadline())
|
||||
|
||||
# Try to begin getting difference for the given entry.
|
||||
# Fails if the entry does not have a previously-known state that can be used to get its difference.
|
||||
#
|
||||
# Clears any previous gaps.
|
||||
def try_begin_get_diff(self, entry, reason):
|
||||
if entry not in self.map:
|
||||
# Won't actually be able to get difference for this entry if we don't have a pts to start off from.
|
||||
if entry in self.possible_gaps:
|
||||
raise RuntimeError('Should not have a possible_gap for an entry not in the state map')
|
||||
|
||||
if __debug__:
|
||||
self._trace('Should get difference for %r because %s but cannot due to missing hash', entry, reason)
|
||||
return
|
||||
|
||||
if __debug__:
|
||||
self._trace('Marking %r as needing difference because %s', entry, reason)
|
||||
self.getting_diff_for.add(entry)
|
||||
self.possible_gaps.pop(entry, None)
|
||||
|
||||
# Finish getting difference for the given entry.
|
||||
#
|
||||
# It also resets the deadline.
|
||||
def end_get_diff(self, entry):
|
||||
try:
|
||||
self.getting_diff_for.remove(entry)
|
||||
except KeyError:
|
||||
raise RuntimeError('Called end_get_diff on an entry which was not getting diff for')
|
||||
|
||||
self.reset_deadlines({entry}, next_updates_deadline())
|
||||
assert entry not in self.possible_gaps, "gaps shouldn't be created while getting difference"
|
||||
|
||||
# endregion Creation, querying, and setting base state.
|
||||
|
||||
# region "Normal" updates flow (processing and detection of gaps).
|
||||
|
||||
# Process an update and return what should be done with it.
|
||||
#
|
||||
# Updates corresponding to entries for which their difference is currently being fetched
|
||||
# will be ignored. While according to the [updates' documentation]:
|
||||
#
|
||||
# > Implementations [have] to postpone updates received via the socket while
|
||||
# > filling gaps in the event and `Update` sequences, as well as avoid filling
|
||||
# > gaps in the same sequence.
|
||||
#
|
||||
# In practice, these updates should have also been retrieved through getting difference.
|
||||
#
|
||||
# [updates documentation] https://core.telegram.org/api/updates
|
||||
def process_updates(
|
||||
self,
|
||||
updates,
|
||||
chat_hashes,
|
||||
result, # out list of updates; returns list of user, chat, or raise if gap
|
||||
):
|
||||
|
||||
# v1 has never sent updates produced by the client itself to the handlers.
|
||||
# However proper update handling requires those to be processed.
|
||||
# This is an ugly workaround for that.
|
||||
self_outgoing = getattr(updates, '_self_outgoing', False)
|
||||
real_result = result
|
||||
result = []
|
||||
|
||||
date = getattr(updates, 'date', None)
|
||||
seq = getattr(updates, 'seq', None)
|
||||
seq_start = getattr(updates, 'seq_start', None)
|
||||
users = getattr(updates, 'users', None) or []
|
||||
chats = getattr(updates, 'chats', None) or []
|
||||
|
||||
if __debug__:
|
||||
self._trace('Processing updates with seq = %r, seq_start = %r, date = %s: %s',
|
||||
seq, seq_start, date.isoformat() if date else None, updates)
|
||||
|
||||
if date is None:
|
||||
# updatesTooLong is the only one with no date (we treat it as a gap)
|
||||
self.try_begin_get_diff(ENTRY_ACCOUNT, 'received updatesTooLong')
|
||||
raise GapError
|
||||
if seq is None:
|
||||
seq = NO_SEQ
|
||||
if seq_start is None:
|
||||
seq_start = seq
|
||||
|
||||
# updateShort is the only update which cannot be dispatched directly but doesn't have 'updates' field
|
||||
updates = getattr(updates, 'updates', None) or [updates.update if isinstance(updates, tl.UpdateShort) else updates]
|
||||
|
||||
for u in updates:
|
||||
u._self_outgoing = self_outgoing
|
||||
|
||||
# > For all the other [not `updates` or `updatesCombined`] `Updates` type constructors
|
||||
# > there is no need to check `seq` or change a local state.
|
||||
if seq_start != NO_SEQ:
|
||||
if self.seq + 1 > seq_start:
|
||||
# Skipping updates that were already handled
|
||||
if __debug__:
|
||||
self._trace('Skipping updates as they should have already been handled')
|
||||
return (users, chats)
|
||||
elif self.seq + 1 < seq_start:
|
||||
# Gap detected
|
||||
self.try_begin_get_diff(ENTRY_ACCOUNT, 'detected gap')
|
||||
raise GapError
|
||||
# else apply
|
||||
|
||||
def _sort_gaps(update):
|
||||
pts = PtsInfo.from_update(update)
|
||||
return pts.pts - pts.pts_count if pts else 0
|
||||
|
||||
reset_deadlines = set() # temporary buffer
|
||||
any_pts_applied = [False] # using a list to pass "by reference"
|
||||
|
||||
result.extend(filter(None, (
|
||||
self.apply_pts_info(u, reset_deadlines=reset_deadlines, any_pts_applied=any_pts_applied)
|
||||
# Telegram can send updates out of order (e.g. ReadChannelInbox first
|
||||
# and then NewChannelMessage, both with the same pts, but the count is
|
||||
# 0 and 1 respectively), so we sort them first.
|
||||
for u in sorted(updates, key=_sort_gaps))))
|
||||
|
||||
# > If the updates were applied, local *Updates* state must be updated
|
||||
# > with `seq` (unless it's 0) and `date` from the constructor.
|
||||
#
|
||||
# By "were applied", we assume it means "some other pts was applied".
|
||||
# Updates which can be applied in any order, such as `UpdateChat`,
|
||||
# should not cause `seq` to be updated (or upcoming updates such as
|
||||
# `UpdateChatParticipant` could be missed).
|
||||
if any_pts_applied[0]:
|
||||
if __debug__:
|
||||
self._trace('Updating seq as local pts was updated too')
|
||||
if date != epoch():
|
||||
self.date = date
|
||||
if seq != NO_SEQ:
|
||||
self.seq = seq
|
||||
|
||||
self.reset_deadlines(reset_deadlines, next_updates_deadline())
|
||||
|
||||
if self.possible_gaps:
|
||||
if __debug__:
|
||||
self._trace('Trying to re-apply %r possible gaps', len(self.possible_gaps))
|
||||
|
||||
# For each update in possible gaps, see if the gap has been resolved already.
|
||||
for key in list(self.possible_gaps.keys()):
|
||||
self.possible_gaps[key].updates.sort(key=_sort_gaps)
|
||||
|
||||
for _ in range(len(self.possible_gaps[key].updates)):
|
||||
update = self.possible_gaps[key].updates.pop(0)
|
||||
|
||||
# If this fails to apply, it will get re-inserted at the end.
|
||||
# All should fail, so the order will be preserved (it would've cycled once).
|
||||
update = self.apply_pts_info(update, reset_deadlines=None)
|
||||
if update:
|
||||
result.append(update)
|
||||
if __debug__:
|
||||
self._trace('Resolved gap with %r: %s', PtsInfo.from_update(update), update)
|
||||
|
||||
# Clear now-empty gaps.
|
||||
self.possible_gaps = {entry: gap for entry, gap in self.possible_gaps.items() if gap.updates}
|
||||
|
||||
real_result.extend(u for u in result if not u._self_outgoing)
|
||||
|
||||
return (users, chats)
|
||||
|
||||
# Tries to apply the input update if its `PtsInfo` follows the correct order.
|
||||
#
|
||||
# If the update can be applied, it is returned; otherwise, the update is stored in a
|
||||
# possible gap (unless it was already handled or would be handled through getting
|
||||
# difference) and `None` is returned.
|
||||
def apply_pts_info(
|
||||
self,
|
||||
update,
|
||||
*,
|
||||
reset_deadlines,
|
||||
any_pts_applied=[True], # mutable default is fine as it's write-only
|
||||
):
|
||||
# This update means we need to call getChannelDifference to get the updates from the channel
|
||||
if isinstance(update, tl.UpdateChannelTooLong):
|
||||
self.try_begin_get_diff(update.channel_id, 'received updateChannelTooLong')
|
||||
return None
|
||||
|
||||
pts = PtsInfo.from_update(update)
|
||||
if not pts:
|
||||
# No pts means that the update can be applied in any order.
|
||||
if __debug__:
|
||||
self._trace('No pts in update, so it can be applied in any order: %s', update)
|
||||
return update
|
||||
|
||||
# As soon as we receive an update of any form related to messages (has `PtsInfo`),
|
||||
# the "no updates" period for that entry is reset.
|
||||
#
|
||||
# Build the `HashSet` to avoid calling `reset_deadline` more than once for the same entry.
|
||||
#
|
||||
# By the time this method returns, self.map will have an entry for which we can reset its deadline.
|
||||
if reset_deadlines:
|
||||
reset_deadlines.add(pts.entry)
|
||||
|
||||
if pts.entry in self.getting_diff_for:
|
||||
# Note: early returning here also prevents gap from being inserted (which they should
|
||||
# not be while getting difference).
|
||||
if __debug__:
|
||||
self._trace('Skipping update with %r as its difference is being fetched', pts)
|
||||
return None
|
||||
|
||||
if pts.entry in self.map:
|
||||
local_pts = self.map[pts.entry].pts
|
||||
if local_pts + pts.pts_count > pts.pts:
|
||||
# Ignore
|
||||
if __debug__:
|
||||
self._trace('Skipping update since local pts %r > %r: %s', local_pts, pts, update)
|
||||
return None
|
||||
elif local_pts + pts.pts_count < pts.pts:
|
||||
# Possible gap
|
||||
# TODO store chats too?
|
||||
if __debug__:
|
||||
self._trace('Possible gap since local pts %r < %r: %s', local_pts, pts, update)
|
||||
if pts.entry not in self.possible_gaps:
|
||||
self.possible_gaps[pts.entry] = PossibleGap(
|
||||
deadline=get_running_loop().time() + POSSIBLE_GAP_TIMEOUT,
|
||||
updates=[]
|
||||
)
|
||||
|
||||
self.possible_gaps[pts.entry].updates.append(update)
|
||||
return None
|
||||
else:
|
||||
# Apply
|
||||
any_pts_applied[0] = True
|
||||
if __debug__:
|
||||
self._trace('Applying update pts since local pts %r = %r: %s', local_pts, pts, update)
|
||||
|
||||
# In a channel, we may immediately receive:
|
||||
# * ReadChannelInbox (pts = X, pts_count = 0)
|
||||
# * NewChannelMessage (pts = X, pts_count = 1)
|
||||
#
|
||||
# Notice how both `pts` are the same. If they were to be applied out of order, the first
|
||||
# one however would've triggered a gap because `local_pts` + `pts_count` of 0 would be
|
||||
# less than `remote_pts`. So there is no risk by setting the `local_pts` to match the
|
||||
# `remote_pts` here of missing the new message.
|
||||
#
|
||||
# The message would however be lost if we initialized the pts with the first one, since
|
||||
# the second one would appear "already handled". To prevent this we set the pts to be
|
||||
# one less when the count is 0 (which might be wrong and trigger a gap later on, but is
|
||||
# unlikely). This will prevent us from losing updates in the unlikely scenario where these
|
||||
# two updates arrive in different packets (and therefore couldn't be sorted beforehand).
|
||||
if pts.entry in self.map:
|
||||
self.map[pts.entry].pts = pts.pts
|
||||
else:
|
||||
# When a chat is migrated to a megagroup, the first update can be a `ReadChannelInbox`
|
||||
# with `pts = 1, pts_count = 0` followed by a `NewChannelMessage` with `pts = 2, pts_count=1`.
|
||||
# Note how the `pts` for the message is 2 and not 1 unlike the case described before!
|
||||
# This is likely because the `pts` cannot be 0 (or it would fail with PERSISTENT_TIMESTAMP_EMPTY),
|
||||
# which forces the first update to be 1. But if we got difference with 1 and the second update
|
||||
# also used 1, we would miss it, so Telegram probably uses 2 to work around that.
|
||||
self.map[pts.entry] = State(
|
||||
pts=(pts.pts - (0 if pts.pts_count else 1)) or 1,
|
||||
deadline=next_updates_deadline()
|
||||
)
|
||||
|
||||
return update
|
||||
|
||||
# endregion "Normal" updates flow (processing and detection of gaps).
|
||||
|
||||
# region Getting and applying account difference.
|
||||
|
||||
# Return the request that needs to be made to get the difference, if any.
|
||||
def get_difference(self):
|
||||
for entry in (ENTRY_ACCOUNT, ENTRY_SECRET):
|
||||
if entry in self.getting_diff_for:
|
||||
if entry not in self.map:
|
||||
raise RuntimeError('Should not try to get difference for an entry without known state')
|
||||
|
||||
gd = fn.updates.GetDifferenceRequest(
|
||||
pts=self.map[ENTRY_ACCOUNT].pts,
|
||||
pts_total_limit=None,
|
||||
date=self.date,
|
||||
qts=self.map[ENTRY_SECRET].pts if ENTRY_SECRET in self.map else NO_SEQ,
|
||||
)
|
||||
if __debug__:
|
||||
self._trace('Requesting account difference %s', gd)
|
||||
return gd
|
||||
|
||||
return None
|
||||
|
||||
# Similar to [`MessageBox::process_updates`], but using the result from getting difference.
|
||||
def apply_difference(
|
||||
self,
|
||||
diff,
|
||||
chat_hashes,
|
||||
):
|
||||
if __debug__:
|
||||
self._trace('Applying account difference %s', diff)
|
||||
|
||||
finish = None
|
||||
result = None
|
||||
|
||||
if isinstance(diff, tl.updates.DifferenceEmpty):
|
||||
finish = True
|
||||
self.date = diff.date
|
||||
self.seq = diff.seq
|
||||
result = [], [], []
|
||||
elif isinstance(diff, tl.updates.Difference):
|
||||
finish = True
|
||||
chat_hashes.extend(diff.users, diff.chats)
|
||||
result = self.apply_difference_type(diff, chat_hashes)
|
||||
elif isinstance(diff, tl.updates.DifferenceSlice):
|
||||
finish = False
|
||||
chat_hashes.extend(diff.users, diff.chats)
|
||||
result = self.apply_difference_type(diff, chat_hashes)
|
||||
elif isinstance(diff, tl.updates.DifferenceTooLong):
|
||||
finish = True
|
||||
self.map[ENTRY_ACCOUNT].pts = diff.pts # the deadline will be reset once the diff ends
|
||||
result = [], [], []
|
||||
|
||||
if finish:
|
||||
account = ENTRY_ACCOUNT in self.getting_diff_for
|
||||
secret = ENTRY_SECRET in self.getting_diff_for
|
||||
|
||||
if not account and not secret:
|
||||
raise RuntimeError('Should not be applying the difference when neither account or secret was diff was active')
|
||||
|
||||
# Both may be active if both expired at the same time.
|
||||
if account:
|
||||
self.end_get_diff(ENTRY_ACCOUNT)
|
||||
if secret:
|
||||
self.end_get_diff(ENTRY_SECRET)
|
||||
|
||||
return result
|
||||
|
||||
def apply_difference_type(
|
||||
self,
|
||||
diff,
|
||||
chat_hashes,
|
||||
):
|
||||
state = getattr(diff, 'intermediate_state', None) or diff.state
|
||||
self.set_state(state, reset=False)
|
||||
|
||||
# diff.other_updates can contain things like UpdateChannelTooLong and UpdateNewChannelMessage.
|
||||
# We need to process those as if they were socket updates to discard any we have already handled.
|
||||
updates = []
|
||||
self.process_updates(tl.Updates(
|
||||
updates=diff.other_updates,
|
||||
users=diff.users,
|
||||
chats=diff.chats,
|
||||
date=epoch(),
|
||||
seq=NO_SEQ, # this way date is not used
|
||||
), chat_hashes, updates)
|
||||
|
||||
updates.extend(tl.UpdateNewMessage(
|
||||
message=m,
|
||||
pts=NO_SEQ,
|
||||
pts_count=NO_SEQ,
|
||||
) for m in diff.new_messages)
|
||||
updates.extend(tl.UpdateNewEncryptedMessage(
|
||||
message=m,
|
||||
qts=NO_SEQ,
|
||||
) for m in diff.new_encrypted_messages)
|
||||
|
||||
return updates, diff.users, diff.chats
|
||||
|
||||
def end_difference(self):
|
||||
if __debug__:
|
||||
self._trace('Ending account difference')
|
||||
|
||||
account = ENTRY_ACCOUNT in self.getting_diff_for
|
||||
secret = ENTRY_SECRET in self.getting_diff_for
|
||||
|
||||
if not account and not secret:
|
||||
raise RuntimeError('Should not be ending get difference when neither account or secret was diff was active')
|
||||
|
||||
# Both may be active if both expired at the same time.
|
||||
if account:
|
||||
self.end_get_diff(ENTRY_ACCOUNT)
|
||||
if secret:
|
||||
self.end_get_diff(ENTRY_SECRET)
|
||||
|
||||
# endregion Getting and applying account difference.
|
||||
|
||||
# region Getting and applying channel difference.
|
||||
|
||||
# Return the request that needs to be made to get a channel's difference, if any.
|
||||
def get_channel_difference(
|
||||
self,
|
||||
chat_hashes,
|
||||
):
|
||||
entry = next((id for id in self.getting_diff_for if isinstance(id, int)), None)
|
||||
if not entry:
|
||||
return None
|
||||
|
||||
packed = chat_hashes.get(entry)
|
||||
if not packed:
|
||||
# Cannot get channel difference as we're missing its hash
|
||||
# TODO we should probably log this
|
||||
self.end_get_diff(entry)
|
||||
# Remove the outdated `pts` entry from the map so that the next update can correct
|
||||
# it. Otherwise, it will spam that the access hash is missing.
|
||||
self.map.pop(entry, None)
|
||||
return None
|
||||
|
||||
state = self.map.get(entry)
|
||||
if not state:
|
||||
raise RuntimeError('Should not try to get difference for an entry without known state')
|
||||
|
||||
gd = fn.updates.GetChannelDifferenceRequest(
|
||||
force=False,
|
||||
channel=tl.InputChannel(packed.id, packed.hash),
|
||||
filter=tl.ChannelMessagesFilterEmpty(),
|
||||
pts=state.pts,
|
||||
limit=BOT_CHANNEL_DIFF_LIMIT if chat_hashes.self_bot else USER_CHANNEL_DIFF_LIMIT
|
||||
)
|
||||
if __debug__:
|
||||
self._trace('Requesting channel difference %s', gd)
|
||||
return gd
|
||||
|
||||
# Similar to [`MessageBox::process_updates`], but using the result from getting difference.
|
||||
def apply_channel_difference(
|
||||
self,
|
||||
request,
|
||||
diff,
|
||||
chat_hashes,
|
||||
):
|
||||
entry = request.channel.channel_id
|
||||
if __debug__:
|
||||
self._trace('Applying channel difference for %r: %s', entry, diff)
|
||||
|
||||
self.possible_gaps.pop(entry, None)
|
||||
|
||||
if isinstance(diff, tl.updates.ChannelDifferenceEmpty):
|
||||
assert diff.final
|
||||
self.end_get_diff(entry)
|
||||
self.map[entry].pts = diff.pts
|
||||
return [], [], []
|
||||
elif isinstance(diff, tl.updates.ChannelDifferenceTooLong):
|
||||
assert diff.final
|
||||
self.map[entry].pts = diff.dialog.pts
|
||||
chat_hashes.extend(diff.users, diff.chats)
|
||||
self.reset_channel_deadline(entry, diff.timeout)
|
||||
# This `diff` has the "latest messages and corresponding chats", but it would
|
||||
# be strange to give the user only partial changes of these when they would
|
||||
# expect all updates to be fetched. Instead, nothing is returned.
|
||||
return [], [], []
|
||||
elif isinstance(diff, tl.updates.ChannelDifference):
|
||||
if diff.final:
|
||||
self.end_get_diff(entry)
|
||||
|
||||
self.map[entry].pts = diff.pts
|
||||
chat_hashes.extend(diff.users, diff.chats)
|
||||
|
||||
updates = []
|
||||
self.process_updates(tl.Updates(
|
||||
updates=diff.other_updates,
|
||||
users=diff.users,
|
||||
chats=diff.chats,
|
||||
date=epoch(),
|
||||
seq=NO_SEQ, # this way date is not used
|
||||
), chat_hashes, updates)
|
||||
|
||||
updates.extend(tl.UpdateNewChannelMessage(
|
||||
message=m,
|
||||
pts=NO_SEQ,
|
||||
pts_count=NO_SEQ,
|
||||
) for m in diff.new_messages)
|
||||
self.reset_channel_deadline(entry, None)
|
||||
|
||||
return updates, diff.users, diff.chats
|
||||
|
||||
def end_channel_difference(self, request, reason: PrematureEndReason, chat_hashes):
|
||||
entry = request.channel.channel_id
|
||||
if __debug__:
|
||||
self._trace('Ending channel difference for %r because %s', entry, reason)
|
||||
|
||||
if reason == PrematureEndReason.TEMPORARY_SERVER_ISSUES:
|
||||
# Temporary issues. End getting difference without updating the pts so we can retry later.
|
||||
self.possible_gaps.pop(entry, None)
|
||||
self.end_get_diff(entry)
|
||||
elif reason == PrematureEndReason.BANNED:
|
||||
# Banned in the channel. Forget its state since we can no longer fetch updates from it.
|
||||
self.possible_gaps.pop(entry, None)
|
||||
self.end_get_diff(entry)
|
||||
del self.map[entry]
|
||||
else:
|
||||
raise RuntimeError('Unknown reason to end channel difference')
|
||||
|
||||
# endregion Getting and applying channel difference.
|
||||
|
|
@ -1,195 +0,0 @@
|
|||
from typing import Optional, Tuple
|
||||
from enum import IntEnum
|
||||
from ..tl.types import InputPeerUser, InputPeerChat, InputPeerChannel
|
||||
|
||||
|
||||
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')
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
user_id: int,
|
||||
dc_id: int,
|
||||
bot: bool,
|
||||
pts: int,
|
||||
qts: int,
|
||||
date: int,
|
||||
seq: int,
|
||||
takeout_id: Optional[int]
|
||||
):
|
||||
self.user_id = user_id
|
||||
self.dc_id = dc_id
|
||||
self.bot = bot
|
||||
self.pts = pts
|
||||
self.qts = qts
|
||||
self.date = date
|
||||
self.seq = seq
|
||||
self.takeout_id = takeout_id
|
||||
|
||||
def __repr__(self):
|
||||
return repr({k: getattr(self, k) for k in self.__slots__})
|
||||
|
||||
|
||||
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')
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
channel_id: int,
|
||||
pts: int,
|
||||
):
|
||||
self.channel_id = channel_id
|
||||
self.pts = pts
|
||||
|
||||
def __repr__(self):
|
||||
return repr({k: getattr(self, k) for k in self.__slots__})
|
||||
|
||||
|
||||
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,
|
||||
}
|
||||
|
||||
|
||||
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')
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
ty: EntityType,
|
||||
id: int,
|
||||
hash: int
|
||||
):
|
||||
self.ty = ty
|
||||
self.id = id
|
||||
self.hash = hash
|
||||
|
||||
@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)
|
||||
|
||||
def _as_input_peer(self):
|
||||
if self.is_user:
|
||||
return InputPeerUser(self.id, self.hash)
|
||||
elif self.ty == EntityType.GROUP:
|
||||
return InputPeerChat(self.id)
|
||||
else:
|
||||
return InputPeerChannel(self.id, self.hash)
|
||||
|
||||
def __repr__(self):
|
||||
return repr({k: getattr(self, k) for k in self.__slots__})
|
||||
|
|
@ -19,7 +19,6 @@ from .messages import MessageMethods
|
|||
from .chats import ChatMethods
|
||||
from .dialogs import DialogMethods
|
||||
from .downloads import DownloadMethods
|
||||
from .account import AccountMethods
|
||||
from .auth import AuthMethods
|
||||
from .bots import BotMethods
|
||||
from .telegramclient import TelegramClient
|
||||
|
|
|
|||
|
|
@ -1,243 +0,0 @@
|
|||
import functools
|
||||
import inspect
|
||||
import typing
|
||||
|
||||
from .users import _NOT_A_REQUEST
|
||||
from .. import helpers, utils
|
||||
from ..tl import functions, TLRequest
|
||||
|
||||
if typing.TYPE_CHECKING:
|
||||
from .telegramclient import TelegramClient
|
||||
|
||||
|
||||
# TODO Make use of :tl:`InvokeWithMessagesRange` somehow
|
||||
# For that, we need to use :tl:`GetSplitRanges` first.
|
||||
class _TakeoutClient:
|
||||
"""
|
||||
Proxy object over the client.
|
||||
"""
|
||||
__PROXY_INTERFACE = ('__enter__', '__exit__', '__aenter__', '__aexit__')
|
||||
|
||||
def __init__(self, finalize, client, request):
|
||||
# We use the name mangling for attributes to make them inaccessible
|
||||
# from within the shadowed client object and to distinguish them from
|
||||
# its own attributes where needed.
|
||||
self.__finalize = finalize
|
||||
self.__client = client
|
||||
self.__request = request
|
||||
self.__success = None
|
||||
|
||||
@property
|
||||
def success(self):
|
||||
return self.__success
|
||||
|
||||
@success.setter
|
||||
def success(self, value):
|
||||
self.__success = value
|
||||
|
||||
async def __aenter__(self):
|
||||
# Enter/Exit behaviour is "overrode", we don't want to call start.
|
||||
client = self.__client
|
||||
if client.session.takeout_id is None:
|
||||
client.session.takeout_id = (await client(self.__request)).id
|
||||
elif self.__request is not None:
|
||||
raise ValueError("Can't send a takeout request while another "
|
||||
"takeout for the current session still not been finished yet.")
|
||||
return self
|
||||
|
||||
async def __aexit__(self, exc_type, exc_value, traceback):
|
||||
if self.__success is None and self.__finalize:
|
||||
self.__success = exc_type is None
|
||||
|
||||
if self.__success is not None:
|
||||
result = await self(functions.account.FinishTakeoutSessionRequest(
|
||||
self.__success))
|
||||
if not result:
|
||||
raise ValueError("Failed to finish the takeout.")
|
||||
self.session.takeout_id = None
|
||||
|
||||
__enter__ = helpers._sync_enter
|
||||
__exit__ = helpers._sync_exit
|
||||
|
||||
async def __call__(self, request, ordered=False):
|
||||
takeout_id = self.__client.session.takeout_id
|
||||
if takeout_id is None:
|
||||
raise ValueError('Takeout mode has not been initialized '
|
||||
'(are you calling outside of "with"?)')
|
||||
|
||||
single = not utils.is_list_like(request)
|
||||
requests = ((request,) if single else request)
|
||||
wrapped = []
|
||||
for r in requests:
|
||||
if not isinstance(r, TLRequest):
|
||||
raise _NOT_A_REQUEST()
|
||||
await r.resolve(self, utils)
|
||||
wrapped.append(functions.InvokeWithTakeoutRequest(takeout_id, r))
|
||||
|
||||
return await self.__client(
|
||||
wrapped[0] if single else wrapped, ordered=ordered)
|
||||
|
||||
def __getattribute__(self, name):
|
||||
# We access class via type() because __class__ will recurse infinitely.
|
||||
# Also note that since we've name-mangled our own class attributes,
|
||||
# they'll be passed to __getattribute__() as already decorated. For
|
||||
# example, 'self.__client' will be passed as '_TakeoutClient__client'.
|
||||
# https://docs.python.org/3/tutorial/classes.html#private-variables
|
||||
if name.startswith('__') and name not in type(self).__PROXY_INTERFACE:
|
||||
raise AttributeError # force call of __getattr__
|
||||
|
||||
# Try to access attribute in the proxy object and check for the same
|
||||
# attribute in the shadowed object (through our __getattr__) if failed.
|
||||
return super().__getattribute__(name)
|
||||
|
||||
def __getattr__(self, name):
|
||||
value = getattr(self.__client, name)
|
||||
if inspect.ismethod(value):
|
||||
# Emulate bound methods behavior by partially applying our proxy
|
||||
# class as the self parameter instead of the client.
|
||||
return functools.partial(
|
||||
getattr(self.__client.__class__, name), self)
|
||||
|
||||
return value
|
||||
|
||||
def __setattr__(self, name, value):
|
||||
if name.startswith('_{}__'.format(type(self).__name__.lstrip('_'))):
|
||||
# This is our own name-mangled attribute, keep calm.
|
||||
return super().__setattr__(name, value)
|
||||
return setattr(self.__client, name, value)
|
||||
|
||||
|
||||
class AccountMethods:
|
||||
def takeout(
|
||||
self: 'TelegramClient',
|
||||
finalize: bool = True,
|
||||
*,
|
||||
contacts: bool = None,
|
||||
users: bool = None,
|
||||
chats: bool = None,
|
||||
megagroups: bool = None,
|
||||
channels: bool = None,
|
||||
files: bool = None,
|
||||
max_file_size: bool = None) -> 'TelegramClient':
|
||||
"""
|
||||
Returns a :ref:`telethon-client` which calls methods behind a takeout session.
|
||||
|
||||
It does so by creating a proxy object over the current client through
|
||||
which making requests will use :tl:`InvokeWithTakeoutRequest` to wrap
|
||||
them. In other words, returns the current client modified so that
|
||||
requests are done as a takeout:
|
||||
|
||||
Some of the calls made through the takeout session will have lower
|
||||
flood limits. This is useful if you want to export the data from
|
||||
conversations or mass-download media, since the rate limits will
|
||||
be lower. Only some requests will be affected, and you will need
|
||||
to adjust the `wait_time` of methods like `client.iter_messages
|
||||
<telethon.client.messages.MessageMethods.iter_messages>`.
|
||||
|
||||
By default, all parameters are `None`, and you need to enable those
|
||||
you plan to use by setting them to either `True` or `False`.
|
||||
|
||||
You should ``except errors.TakeoutInitDelayError as e``, since this
|
||||
exception will raise depending on the condition of the session. You
|
||||
can then access ``e.seconds`` to know how long you should wait for
|
||||
before calling the method again.
|
||||
|
||||
There's also a `success` property available in the takeout proxy
|
||||
object, so from the `with` body you can set the boolean result that
|
||||
will be sent back to Telegram. But if it's left `None` as by
|
||||
default, then the action is based on the `finalize` parameter. If
|
||||
it's `True` then the takeout will be finished, and if no exception
|
||||
occurred during it, then `True` will be considered as a result.
|
||||
Otherwise, the takeout will not be finished and its ID will be
|
||||
preserved for future usage as `client.session.takeout_id
|
||||
<telethon.sessions.abstract.Session.takeout_id>`.
|
||||
|
||||
Arguments
|
||||
finalize (`bool`):
|
||||
Whether the takeout session should be finalized upon
|
||||
exit or not.
|
||||
|
||||
contacts (`bool`):
|
||||
Set to `True` if you plan on downloading contacts.
|
||||
|
||||
users (`bool`):
|
||||
Set to `True` if you plan on downloading information
|
||||
from users and their private conversations with you.
|
||||
|
||||
chats (`bool`):
|
||||
Set to `True` if you plan on downloading information
|
||||
from small group chats, such as messages and media.
|
||||
|
||||
megagroups (`bool`):
|
||||
Set to `True` if you plan on downloading information
|
||||
from megagroups (channels), such as messages and media.
|
||||
|
||||
channels (`bool`):
|
||||
Set to `True` if you plan on downloading information
|
||||
from broadcast channels, such as messages and media.
|
||||
|
||||
files (`bool`):
|
||||
Set to `True` if you plan on downloading media and
|
||||
you don't only wish to export messages.
|
||||
|
||||
max_file_size (`int`):
|
||||
The maximum file size, in bytes, that you plan
|
||||
to download for each message with media.
|
||||
|
||||
Example
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import errors
|
||||
|
||||
try:
|
||||
async with client.takeout() as takeout:
|
||||
await client.get_messages('me') # normal call
|
||||
await takeout.get_messages('me') # wrapped through takeout (less limits)
|
||||
|
||||
async for message in takeout.iter_messages(chat, wait_time=0):
|
||||
... # Do something with the message
|
||||
|
||||
except errors.TakeoutInitDelayError as e:
|
||||
print('Must wait', e.seconds, 'before takeout')
|
||||
"""
|
||||
request_kwargs = dict(
|
||||
contacts=contacts,
|
||||
message_users=users,
|
||||
message_chats=chats,
|
||||
message_megagroups=megagroups,
|
||||
message_channels=channels,
|
||||
files=files,
|
||||
file_max_size=max_file_size
|
||||
)
|
||||
arg_specified = (arg is not None for arg in request_kwargs.values())
|
||||
|
||||
if self.session.takeout_id is None or any(arg_specified):
|
||||
request = functions.account.InitTakeoutSessionRequest(
|
||||
**request_kwargs)
|
||||
else:
|
||||
request = None
|
||||
|
||||
return _TakeoutClient(finalize, self, request)
|
||||
|
||||
async def end_takeout(self: 'TelegramClient', success: bool) -> bool:
|
||||
"""
|
||||
Finishes the current takeout session.
|
||||
|
||||
Arguments
|
||||
success (`bool`):
|
||||
Whether the takeout completed successfully or not.
|
||||
|
||||
Returns
|
||||
`True` if the operation was successful, `False` otherwise.
|
||||
|
||||
Example
|
||||
.. code-block:: python
|
||||
|
||||
await client.end_takeout(success=False)
|
||||
"""
|
||||
try:
|
||||
async with _TakeoutClient(True, self, None) as takeout:
|
||||
takeout.success = success
|
||||
except ValueError:
|
||||
return False
|
||||
return True
|
||||
|
|
@ -1,44 +1,48 @@
|
|||
import getpass
|
||||
import hashlib
|
||||
import inspect
|
||||
import os
|
||||
import sys
|
||||
import typing
|
||||
import warnings
|
||||
|
||||
from .. import utils, helpers, errors, password as pwd_mod
|
||||
from ..tl import types, functions, custom
|
||||
from .._updates import SessionState
|
||||
|
||||
if typing.TYPE_CHECKING:
|
||||
from .telegramclient import TelegramClient
|
||||
from .messageparse import MessageParseMethods
|
||||
from .users import UserMethods
|
||||
from .. import utils, helpers, errors
|
||||
from ..tl import types, functions
|
||||
|
||||
|
||||
class AuthMethods:
|
||||
class AuthMethods(MessageParseMethods, UserMethods):
|
||||
|
||||
# region Public methods
|
||||
|
||||
def start(
|
||||
self: 'TelegramClient',
|
||||
phone: typing.Union[typing.Callable[[], str], str] = lambda: input('Please enter your phone (or bot token): '),
|
||||
password: typing.Union[typing.Callable[[], str], str] = lambda: getpass.getpass('Please enter your password: '),
|
||||
self,
|
||||
phone=lambda: input('Please enter your phone (or bot token): '),
|
||||
password=lambda: getpass.getpass('Please enter your password: '),
|
||||
*,
|
||||
bot_token: str = None,
|
||||
force_sms: bool = False,
|
||||
code_callback: typing.Callable[[], typing.Union[str, int]] = None,
|
||||
first_name: str = 'New User',
|
||||
last_name: str = '',
|
||||
max_attempts: int = 3) -> 'TelegramClient':
|
||||
bot_token=None, force_sms=False, code_callback=None,
|
||||
first_name='New User', last_name='', max_attempts=3):
|
||||
"""
|
||||
Starts the client (connects and logs in if necessary).
|
||||
Convenience method to interactively connect and sign in if required,
|
||||
also taking into consideration that 2FA may be enabled in the account.
|
||||
|
||||
By default, this method will be interactive (asking for
|
||||
user input if needed), and will handle 2FA if enabled too.
|
||||
If the phone doesn't belong to an existing account (and will hence
|
||||
`sign_up` for a new one), **you are agreeing to Telegram's
|
||||
Terms of Service. This is required and your account
|
||||
will be banned otherwise.** See https://telegram.org/tos
|
||||
and https://core.telegram.org/api/terms.
|
||||
|
||||
Example usage:
|
||||
>>> client = ...
|
||||
>>> client.start(phone)
|
||||
Please enter the code you received: 12345
|
||||
Please enter your password: *******
|
||||
(You are now logged in)
|
||||
|
||||
If the event loop is already running, this method returns a
|
||||
coroutine that you should await on your own code; otherwise
|
||||
the loop is ran until said coroutine completes.
|
||||
|
||||
Arguments
|
||||
Args:
|
||||
phone (`str` | `int` | `callable`):
|
||||
The phone (or callable without arguments to get it)
|
||||
to which the code will be sent. If a bot-token-like
|
||||
|
|
@ -75,27 +79,9 @@ class AuthMethods:
|
|||
How many times the code/password callback should be
|
||||
retried or switching between signing in and signing up.
|
||||
|
||||
Returns
|
||||
Returns:
|
||||
This `TelegramClient`, so initialization
|
||||
can be chained with ``.start()``.
|
||||
|
||||
Example
|
||||
.. code-block:: python
|
||||
|
||||
client = TelegramClient('anon', api_id, api_hash)
|
||||
|
||||
# Starting as a bot account
|
||||
await client.start(bot_token=bot_token)
|
||||
|
||||
# Starting as a user account
|
||||
await client.start(phone)
|
||||
# Please enter the code you received: 12345
|
||||
# Please enter your password: *******
|
||||
# (You are now logged in)
|
||||
|
||||
# Starting using a context manager (this calls start()):
|
||||
with client:
|
||||
pass
|
||||
"""
|
||||
if code_callback is None:
|
||||
def code_callback():
|
||||
|
|
@ -129,36 +115,12 @@ class AuthMethods:
|
|||
)
|
||||
|
||||
async def _start(
|
||||
self: 'TelegramClient', phone, password, bot_token, force_sms,
|
||||
self, phone, password, bot_token, force_sms,
|
||||
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; '
|
||||
'if you were expecting a different user, check whether '
|
||||
'you are accidentally reusing an existing session'
|
||||
)
|
||||
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; '
|
||||
'if you were expecting a different user, check whether '
|
||||
'you are accidentally reusing an existing session'
|
||||
)
|
||||
|
||||
if await self.is_user_authorized():
|
||||
return self
|
||||
|
||||
if not bot_token:
|
||||
|
|
@ -183,7 +145,8 @@ class AuthMethods:
|
|||
attempts = 0
|
||||
two_step_detected = False
|
||||
|
||||
await self.send_code_request(phone, force_sms=force_sms)
|
||||
sent_code = await self.send_code_request(phone, force_sms=force_sms)
|
||||
sign_up = not sent_code.phone_registered
|
||||
while attempts < max_attempts:
|
||||
try:
|
||||
value = code_callback()
|
||||
|
|
@ -196,12 +159,19 @@ class AuthMethods:
|
|||
if not value:
|
||||
raise errors.PhoneCodeEmptyError(request=None)
|
||||
|
||||
# Raises SessionPasswordNeededError if 2FA enabled
|
||||
me = await self.sign_in(phone, code=value)
|
||||
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,
|
||||
|
|
@ -235,58 +205,29 @@ class AuthMethods:
|
|||
print('Invalid password. Please try again',
|
||||
file=sys.stderr)
|
||||
else:
|
||||
raise errors.PasswordHashInvalidError(request=None)
|
||||
raise errors.PasswordHashInvalidError(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)
|
||||
tos = '; remember to not break the ToS or you will risk an account ban!'
|
||||
signed, name = 'Signed in successfully as', utils.get_display_name(me)
|
||||
try:
|
||||
print(signed, name, tos, sep='')
|
||||
print(signed, name)
|
||||
except UnicodeEncodeError:
|
||||
# Some terminals don't support certain characters
|
||||
print(signed, name.encode('utf-8', errors='ignore')
|
||||
.decode('ascii', errors='ignore'), tos, sep='')
|
||||
.decode('ascii', errors='ignore'))
|
||||
|
||||
return self
|
||||
|
||||
def _parse_phone_and_hash(self, phone, phone_hash):
|
||||
"""
|
||||
Helper method to both parse and validate phone and its hash.
|
||||
"""
|
||||
phone = utils.parse_phone(phone) or self._phone
|
||||
if not phone:
|
||||
raise ValueError(
|
||||
'Please make sure to call send_code_request first.'
|
||||
)
|
||||
|
||||
phone_hash = phone_hash or self._phone_code_hash.get(phone, None)
|
||||
if not phone_hash:
|
||||
raise ValueError('You also need to provide a phone_code_hash.')
|
||||
|
||||
return phone, phone_hash
|
||||
|
||||
async def sign_in(
|
||||
self: 'TelegramClient',
|
||||
phone: str = None,
|
||||
code: typing.Union[str, int] = None,
|
||||
*,
|
||||
password: str = None,
|
||||
bot_token: str = None,
|
||||
phone_code_hash: str = None) -> 'typing.Union[types.User, types.auth.SentCode]':
|
||||
self, phone=None, code=None, *, password=None,
|
||||
bot_token=None, phone_code_hash=None):
|
||||
"""
|
||||
Logs in to Telegram to an existing user or bot account.
|
||||
Starts or completes the sign in process with the given phone number
|
||||
or code that Telegram sent.
|
||||
|
||||
You should only use this if you are not authorized yet.
|
||||
|
||||
This method will send the code if it's not provided.
|
||||
|
||||
.. note::
|
||||
|
||||
In most cases, you should simply use `start()` and not this method.
|
||||
|
||||
Arguments
|
||||
Args:
|
||||
phone (`str` | `int`):
|
||||
The phone to send the code to if no code was provided,
|
||||
or to override the phone that was previously used with
|
||||
|
|
@ -300,29 +241,19 @@ class AuthMethods:
|
|||
|
||||
password (`str`):
|
||||
2FA password, should be used if a previous call raised
|
||||
``SessionPasswordNeededError``.
|
||||
SessionPasswordNeededError.
|
||||
|
||||
bot_token (`str`):
|
||||
Used to sign in as a bot. Not all requests will be available.
|
||||
This should be the hash the `@BotFather <https://t.me/BotFather>`_
|
||||
gave you.
|
||||
This should be the hash the @BotFather gave you.
|
||||
|
||||
phone_code_hash (`str`, optional):
|
||||
The hash returned by `send_code_request`. This can be left as
|
||||
`None` to use the last hash known for the phone to be used.
|
||||
phone_code_hash (`str`):
|
||||
The hash returned by .send_code_request. This can be set to None
|
||||
to use the last hash known.
|
||||
|
||||
Returns
|
||||
Returns:
|
||||
The signed in user, or the information about
|
||||
:meth:`send_code_request`.
|
||||
|
||||
Example
|
||||
.. code-block:: python
|
||||
|
||||
phone = '+34 123 123 123'
|
||||
await client.sign_in(phone) # send code
|
||||
|
||||
code = input('enter code: ')
|
||||
await client.sign_in(phone, code)
|
||||
"""
|
||||
me = await self.get_me()
|
||||
if me:
|
||||
|
|
@ -331,347 +262,248 @@ class AuthMethods:
|
|||
if phone and not code and not password:
|
||||
return await self.send_code_request(phone)
|
||||
elif code:
|
||||
phone, phone_code_hash = \
|
||||
self._parse_phone_and_hash(phone, phone_code_hash)
|
||||
phone = utils.parse_phone(phone) or self._phone
|
||||
phone_code_hash = \
|
||||
phone_code_hash or self._phone_code_hash.get(phone, None)
|
||||
|
||||
if not phone:
|
||||
raise ValueError(
|
||||
'Please make sure to call send_code_request first.'
|
||||
)
|
||||
if not phone_code_hash:
|
||||
raise ValueError('You also need to provide a phone_code_hash.')
|
||||
|
||||
# May raise PhoneCodeEmptyError, PhoneCodeExpiredError,
|
||||
# PhoneCodeHashEmptyError or PhoneCodeInvalidError.
|
||||
request = functions.auth.SignInRequest(
|
||||
phone, phone_code_hash, str(code)
|
||||
)
|
||||
result = await self(functions.auth.SignInRequest(
|
||||
phone, phone_code_hash, str(code)))
|
||||
elif password:
|
||||
pwd = await self(functions.account.GetPasswordRequest())
|
||||
request = functions.auth.CheckPasswordRequest(
|
||||
pwd_mod.compute_check(pwd, password)
|
||||
)
|
||||
salt = (await self(
|
||||
functions.account.GetPasswordRequest())).current_salt
|
||||
result = await self(functions.auth.CheckPasswordRequest(
|
||||
helpers.get_password_hash(password, salt)
|
||||
))
|
||||
elif bot_token:
|
||||
request = functions.auth.ImportBotAuthorizationRequest(
|
||||
result = await self(functions.auth.ImportBotAuthorizationRequest(
|
||||
flags=0, bot_auth_token=bot_token,
|
||||
api_id=self.api_id, api_hash=self.api_hash
|
||||
)
|
||||
))
|
||||
else:
|
||||
raise ValueError(
|
||||
'You must provide a phone and a code the first time, '
|
||||
'and a password only if an RPCError was raised before.'
|
||||
)
|
||||
|
||||
try:
|
||||
result = await self(request)
|
||||
except errors.PhoneCodeExpiredError:
|
||||
self._phone_code_hash.pop(phone, None)
|
||||
raise
|
||||
self._self_input_peer = utils.get_input_peer(
|
||||
result.user, allow_self=False
|
||||
)
|
||||
return result.user
|
||||
|
||||
if isinstance(result, types.auth.AuthorizationSignUpRequired):
|
||||
# Emulate pre-layer 104 behaviour
|
||||
self._tos = result.terms_of_service
|
||||
raise errors.PhoneNumberUnoccupiedError(request=request)
|
||||
|
||||
return await self._on_login(result.user)
|
||||
|
||||
async def sign_up(
|
||||
self: 'TelegramClient',
|
||||
code: typing.Union[str, int],
|
||||
first_name: str,
|
||||
last_name: str = '',
|
||||
*,
|
||||
phone: str = None,
|
||||
phone_code_hash: str = None) -> 'types.User':
|
||||
async def sign_up(self, code, first_name, last_name=''):
|
||||
"""
|
||||
This method can no longer be used, and will immediately raise a ``ValueError``.
|
||||
See `issue #4050 <https://github.com/LonamiWebs/Telethon/issues/4050>`_ for context.
|
||||
Signs up to Telegram if you don't have an account yet.
|
||||
You must call .send_code_request(phone) first.
|
||||
|
||||
**By using this method you're agreeing to Telegram's
|
||||
Terms of Service. This is required and your account
|
||||
will be banned otherwise.** See https://telegram.org/tos
|
||||
and https://core.telegram.org/api/terms.
|
||||
|
||||
Args:
|
||||
code (`str` | `int`):
|
||||
The code sent by Telegram
|
||||
|
||||
first_name (`str`):
|
||||
The first name to be used by the new account.
|
||||
|
||||
last_name (`str`, optional)
|
||||
Optional last name.
|
||||
|
||||
Returns:
|
||||
The new created :tl:`User`.
|
||||
"""
|
||||
raise ValueError('Third-party applications cannot sign up for Telegram. See https://github.com/LonamiWebs/Telethon/issues/4050 for details')
|
||||
me = await self.get_me()
|
||||
if me:
|
||||
return me
|
||||
|
||||
async def _on_login(self, user):
|
||||
if self._tos and self._tos.text:
|
||||
if self.parse_mode:
|
||||
t = self.parse_mode.unparse(self._tos.text, self._tos.entities)
|
||||
else:
|
||||
t = self._tos.text
|
||||
sys.stderr.write("{}\n".format(t))
|
||||
sys.stderr.flush()
|
||||
|
||||
result = await self(functions.auth.SignUpRequest(
|
||||
phone_number=self._phone,
|
||||
phone_code_hash=self._phone_code_hash.get(self._phone, ''),
|
||||
phone_code=str(code),
|
||||
first_name=first_name,
|
||||
last_name=last_name
|
||||
))
|
||||
|
||||
if self._tos:
|
||||
await self(
|
||||
functions.help.AcceptTermsOfServiceRequest(self._tos.id))
|
||||
|
||||
self._self_input_peer = utils.get_input_peer(
|
||||
result.user, allow_self=False
|
||||
)
|
||||
return result.user
|
||||
|
||||
async def send_code_request(self, phone, *, force_sms=False):
|
||||
"""
|
||||
Callback called whenever the login or sign up process completes.
|
||||
Sends a code request to the specified phone number.
|
||||
|
||||
Returns the input user parameter.
|
||||
"""
|
||||
self._mb_entity_cache.set_self_user(user.id, user.bot, user.access_hash)
|
||||
self._authorized = True
|
||||
|
||||
state = await self(functions.updates.GetStateRequest())
|
||||
# the server may send an old qts in getState
|
||||
difference = await self(functions.updates.GetDifferenceRequest(pts=state.pts, date=state.date, qts=state.qts))
|
||||
|
||||
if isinstance(difference, types.updates.Difference):
|
||||
state = difference.state
|
||||
elif isinstance(difference, types.updates.DifferenceSlice):
|
||||
state = difference.intermediate_state
|
||||
elif isinstance(difference, types.updates.DifferenceTooLong):
|
||||
state.pts = difference.pts
|
||||
|
||||
self._message_box.load(SessionState(0, 0, 0, state.pts, state.qts, int(state.date.timestamp()), state.seq, 0), [])
|
||||
|
||||
return user
|
||||
|
||||
async def send_code_request(
|
||||
self: 'TelegramClient',
|
||||
phone: str,
|
||||
*,
|
||||
force_sms: bool = False,
|
||||
_retry_count: int = 0) -> 'types.auth.SentCode':
|
||||
"""
|
||||
Sends the Telegram code needed to login to the given phone number.
|
||||
|
||||
Arguments
|
||||
Args:
|
||||
phone (`str` | `int`):
|
||||
The phone to which the code will be sent.
|
||||
|
||||
force_sms (`bool`, optional):
|
||||
Whether to force sending as SMS. This has been deprecated.
|
||||
See `issue #4050 <https://github.com/LonamiWebs/Telethon/issues/4050>`_ for context.
|
||||
Whether to force sending as SMS.
|
||||
|
||||
Returns
|
||||
Returns:
|
||||
An instance of :tl:`SentCode`.
|
||||
|
||||
Example
|
||||
.. code-block:: python
|
||||
|
||||
phone = '+34 123 123 123'
|
||||
sent = await client.send_code_request(phone)
|
||||
print(sent)
|
||||
"""
|
||||
if force_sms:
|
||||
warnings.warn('force_sms has been deprecated and no longer works')
|
||||
force_sms = False
|
||||
|
||||
result = None
|
||||
phone = utils.parse_phone(phone) or self._phone
|
||||
phone_hash = self._phone_code_hash.get(phone)
|
||||
|
||||
if not phone_hash:
|
||||
try:
|
||||
result = await self(functions.auth.SendCodeRequest(
|
||||
phone, self.api_id, self.api_hash, types.CodeSettings()))
|
||||
phone, self.api_id, self.api_hash))
|
||||
except errors.AuthRestartError:
|
||||
if _retry_count > 2:
|
||||
raise
|
||||
return await self.send_code_request(
|
||||
phone, force_sms=force_sms, _retry_count=_retry_count+1)
|
||||
return self.send_code_request(phone, force_sms=force_sms)
|
||||
|
||||
# TODO figure out when/if/how this can happen
|
||||
if isinstance(result, types.auth.SentCodeSuccess):
|
||||
raise RuntimeError('logged in right after sending the code')
|
||||
|
||||
# If we already sent a SMS, do not resend the code (hash may be empty)
|
||||
if isinstance(result.type, types.auth.SentCodeTypeSms):
|
||||
force_sms = False
|
||||
|
||||
# phone_code_hash may be empty, if it is, do not save it (#1283)
|
||||
if result.phone_code_hash:
|
||||
self._phone_code_hash[phone] = phone_hash = result.phone_code_hash
|
||||
self._tos = result.terms_of_service
|
||||
self._phone_code_hash[phone] = phone_hash = result.phone_code_hash
|
||||
else:
|
||||
force_sms = True
|
||||
|
||||
self._phone = phone
|
||||
|
||||
if force_sms:
|
||||
try:
|
||||
result = await self(
|
||||
functions.auth.ResendCodeRequest(phone, phone_hash))
|
||||
except errors.PhoneCodeExpiredError:
|
||||
if _retry_count > 2:
|
||||
raise
|
||||
self._phone_code_hash.pop(phone, None)
|
||||
self._log[__name__].info(
|
||||
"Phone code expired in ResendCodeRequest, requesting a new code"
|
||||
)
|
||||
return await self.send_code_request(
|
||||
phone, force_sms=False, _retry_count=_retry_count+1)
|
||||
|
||||
if isinstance(result, types.auth.SentCodeSuccess):
|
||||
raise RuntimeError('logged in right after resending the code')
|
||||
result = await self(
|
||||
functions.auth.ResendCodeRequest(phone, phone_hash))
|
||||
|
||||
self._phone_code_hash[phone] = result.phone_code_hash
|
||||
|
||||
return result
|
||||
|
||||
async def qr_login(self: 'TelegramClient', ignored_ids: typing.List[int] = None) -> custom.QRLogin:
|
||||
"""
|
||||
Initiates the QR login procedure.
|
||||
|
||||
Note that you must be connected before invoking this, as with any
|
||||
other request.
|
||||
|
||||
It is up to the caller to decide how to present the code to the user,
|
||||
whether it's the URL, using the token bytes directly, or generating
|
||||
a QR code and displaying it by other means.
|
||||
|
||||
See the documentation for `QRLogin` to see how to proceed after this.
|
||||
|
||||
Arguments
|
||||
ignored_ids (List[`int`]):
|
||||
List of already logged-in user IDs, to prevent logging in
|
||||
twice with the same user.
|
||||
|
||||
Returns
|
||||
An instance of `QRLogin`.
|
||||
|
||||
Example
|
||||
.. code-block:: python
|
||||
|
||||
def display_url_as_qr(url):
|
||||
pass # do whatever to show url as a qr to the user
|
||||
|
||||
qr_login = await client.qr_login()
|
||||
display_url_as_qr(qr_login.url)
|
||||
|
||||
# Important! You need to wait for the login to complete!
|
||||
await qr_login.wait()
|
||||
|
||||
# If you have 2FA enabled, `wait` will raise `telethon.errors.SessionPasswordNeededError`.
|
||||
# You should except that error and call `sign_in` with the password if this happens.
|
||||
"""
|
||||
qr_login = custom.QRLogin(self, ignored_ids or [])
|
||||
await qr_login.recreate()
|
||||
return qr_login
|
||||
|
||||
async def log_out(self: 'TelegramClient') -> bool:
|
||||
async def log_out(self):
|
||||
"""
|
||||
Logs out Telegram and deletes the current ``*.session`` file.
|
||||
|
||||
The client is unusable after logging out and a new instance should be created.
|
||||
|
||||
Returns
|
||||
`True` if the operation was successful.
|
||||
|
||||
Example
|
||||
.. code-block:: python
|
||||
|
||||
# Note: you will need to login again!
|
||||
await client.log_out()
|
||||
Returns:
|
||||
``True`` if the operation was successful.
|
||||
"""
|
||||
try:
|
||||
await self(functions.auth.LogOutRequest())
|
||||
except errors.RPCError:
|
||||
return False
|
||||
|
||||
self._mb_entity_cache.set_self_user(None, None, None)
|
||||
self._authorized = False
|
||||
|
||||
await self.disconnect()
|
||||
self._self_input_peer = None
|
||||
self._state.pts = -1
|
||||
self.disconnect()
|
||||
self.session.delete()
|
||||
self.session = None
|
||||
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:
|
||||
self, current_password=None, new_password=None,
|
||||
*, hint='', email=None):
|
||||
"""
|
||||
Changes the 2FA settings of the logged in user.
|
||||
|
||||
Review carefully the parameter explanations before using this method.
|
||||
|
||||
Note that this method may be *incredibly* slow depending on the
|
||||
prime numbers that must be used during the process to make sure
|
||||
that everything is safe.
|
||||
Changes the 2FA settings of the logged in user, according to the
|
||||
passed parameters. Take note of the parameter explanations.
|
||||
|
||||
Has no effect if both current and new password are omitted.
|
||||
|
||||
Arguments
|
||||
current_password (`str`, optional):
|
||||
The current password, to authorize changing to ``new_password``.
|
||||
Must be set if changing existing 2FA settings.
|
||||
Must **not** be set if 2FA is currently disabled.
|
||||
Passing this by itself will remove 2FA (if correct).
|
||||
current_password (`str`, optional):
|
||||
The current password, to authorize changing to ``new_password``.
|
||||
Must be set if changing existing 2FA settings.
|
||||
Must **not** be set if 2FA is currently disabled.
|
||||
Passing this by itself will remove 2FA (if correct).
|
||||
|
||||
new_password (`str`, optional):
|
||||
The password to set as 2FA.
|
||||
If 2FA was already enabled, ``current_password`` **must** be set.
|
||||
Leaving this blank or `None` will remove the password.
|
||||
new_password (`str`, optional):
|
||||
The password to set as 2FA.
|
||||
If 2FA was already enabled, ``current_password`` **must** be set.
|
||||
Leaving this blank or ``None`` will remove the password.
|
||||
|
||||
hint (`str`, optional):
|
||||
Hint to be displayed by Telegram when it asks for 2FA.
|
||||
Leaving unspecified is highly discouraged.
|
||||
Has no effect if ``new_password`` is not set.
|
||||
hint (`str`, optional):
|
||||
Hint to be displayed by Telegram when it asks for 2FA.
|
||||
Leaving unspecified is highly discouraged.
|
||||
Has no effect if ``new_password`` is not set.
|
||||
|
||||
email (`str`, optional):
|
||||
Recovery and verification email. If present, you must also
|
||||
set `email_code_callback`, else it raises ``ValueError``.
|
||||
email (`str`, optional):
|
||||
Recovery and verification email. Raises ``EmailUnconfirmedError``
|
||||
if value differs from current one, and has no effect if
|
||||
``new_password`` is not set.
|
||||
|
||||
email_code_callback (`callable`, optional):
|
||||
If an email is provided, a callback that returns the code sent
|
||||
to it must also be set. This callback may be asynchronous.
|
||||
It should return a string with the code. The length of the
|
||||
code will be passed to the callback as an input parameter.
|
||||
|
||||
If the callback returns an invalid code, it will raise
|
||||
``CodeInvalidError``.
|
||||
|
||||
Returns
|
||||
`True` if successful, `False` otherwise.
|
||||
|
||||
Example
|
||||
.. code-block:: python
|
||||
|
||||
# Setting a password for your account which didn't have
|
||||
await client.edit_2fa(new_password='I_<3_Telethon')
|
||||
|
||||
# Removing the password
|
||||
await client.edit_2fa(current_password='I_<3_Telethon')
|
||||
Returns:
|
||||
``True`` if successful, ``False`` otherwise.
|
||||
"""
|
||||
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(functions.account.GetPasswordRequest())
|
||||
pwd.new_algo.salt1 += os.urandom(32)
|
||||
assert isinstance(pwd, types.account.Password)
|
||||
if not pwd.has_password and current_password:
|
||||
pass_result = await self(functions.account.GetPasswordRequest())
|
||||
if isinstance(
|
||||
pass_result, types.account.NoPassword) and current_password:
|
||||
current_password = None
|
||||
|
||||
if current_password:
|
||||
password = pwd_mod.compute_check(pwd, current_password)
|
||||
salt_random = os.urandom(8)
|
||||
salt = pass_result.new_salt + salt_random
|
||||
if not current_password:
|
||||
current_password_hash = salt
|
||||
else:
|
||||
password = types.InputCheckPasswordEmpty()
|
||||
current_password = (
|
||||
pass_result.current_salt
|
||||
+ current_password.encode()
|
||||
+ pass_result.current_salt
|
||||
)
|
||||
current_password_hash = hashlib.sha256(current_password).digest()
|
||||
|
||||
if new_password:
|
||||
new_password_hash = pwd_mod.compute_digest(
|
||||
pwd.new_algo, new_password)
|
||||
else:
|
||||
new_password_hash = b''
|
||||
|
||||
try:
|
||||
await self(functions.account.UpdatePasswordSettingsRequest(
|
||||
password=password,
|
||||
if new_password: # Setting new password
|
||||
new_password = salt + new_password.encode('utf-8') + salt
|
||||
new_password_hash = hashlib.sha256(new_password).digest()
|
||||
new_settings = types.account.PasswordInputSettings(
|
||||
new_salt=salt,
|
||||
new_password_hash=new_password_hash,
|
||||
hint=hint
|
||||
)
|
||||
if email: # If enabling 2FA or changing email
|
||||
new_settings.email = email # TG counts empty string as None
|
||||
return await self(functions.account.UpdatePasswordSettingsRequest(
|
||||
current_password_hash, new_settings=new_settings
|
||||
))
|
||||
else: # Removing existing password
|
||||
return await self(functions.account.UpdatePasswordSettingsRequest(
|
||||
current_password_hash,
|
||||
new_settings=types.account.PasswordInputSettings(
|
||||
new_algo=pwd.new_algo,
|
||||
new_password_hash=new_password_hash,
|
||||
hint=hint,
|
||||
email=email,
|
||||
new_secure_settings=None
|
||||
new_salt=bytes(),
|
||||
new_password_hash=bytes(),
|
||||
hint=hint
|
||||
)
|
||||
))
|
||||
except errors.EmailUnconfirmedError as e:
|
||||
code = email_code_callback(e.code_length)
|
||||
if inspect.isawaitable(code):
|
||||
code = await code
|
||||
|
||||
code = str(code)
|
||||
await self(functions.account.ConfirmPasswordEmailRequest(code))
|
||||
|
||||
return True
|
||||
|
||||
# endregion
|
||||
|
||||
# region with blocks
|
||||
|
||||
def __enter__(self):
|
||||
if self._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 self.start()
|
||||
|
||||
async def __aenter__(self):
|
||||
return await self.start()
|
||||
|
||||
async def __aexit__(self, *args):
|
||||
await self.disconnect()
|
||||
def __exit__(self, *args):
|
||||
self.disconnect()
|
||||
|
||||
__enter__ = helpers._sync_enter
|
||||
__exit__ = helpers._sync_exit
|
||||
async def __aexit__(self, *args):
|
||||
self.disconnect()
|
||||
|
||||
# endregion
|
||||
|
|
|
|||
|
|
@ -1,40 +1,23 @@
|
|||
import typing
|
||||
|
||||
from .. import hints
|
||||
from .users import UserMethods
|
||||
from ..tl import types, functions, custom
|
||||
|
||||
if typing.TYPE_CHECKING:
|
||||
from .telegramclient import TelegramClient
|
||||
|
||||
|
||||
class BotMethods:
|
||||
async def inline_query(
|
||||
self: 'TelegramClient',
|
||||
bot: 'hints.EntityLike',
|
||||
query: str,
|
||||
*,
|
||||
entity: 'hints.EntityLike' = None,
|
||||
offset: str = None,
|
||||
geo_point: 'types.GeoPoint' = None) -> custom.InlineResults:
|
||||
class BotMethods(UserMethods):
|
||||
async def inline_query(self, bot, query, *, offset=None, geo_point=None):
|
||||
"""
|
||||
Makes an inline query to the specified bot (``@vote New Poll``).
|
||||
Makes the given inline query to the specified bot
|
||||
i.e. ``@vote My New Poll`` would be as follows:
|
||||
|
||||
Arguments
|
||||
>>> client = ...
|
||||
>>> client.inline_query('vote', 'My New Poll')
|
||||
|
||||
Args:
|
||||
bot (`entity`):
|
||||
The bot entity to which the inline query should be made.
|
||||
|
||||
query (`str`):
|
||||
The query that should be made to the bot.
|
||||
|
||||
entity (`entity`, optional):
|
||||
The entity where the inline query is being made from. Certain
|
||||
bots use this to display different results depending on where
|
||||
it's used, such as private chats, groups or channels.
|
||||
|
||||
If specified, it will also be the default entity where the
|
||||
message will be sent after clicked. Otherwise, the "empty
|
||||
peer" will be used, which some bots may not handle correctly.
|
||||
|
||||
offset (`str`, optional):
|
||||
The string offset to use for the bot.
|
||||
|
||||
|
|
@ -42,31 +25,17 @@ class BotMethods:
|
|||
The geo point location information to send to the bot
|
||||
for localised results. Available under some bots.
|
||||
|
||||
Returns
|
||||
Returns:
|
||||
A list of `custom.InlineResult
|
||||
<telethon.tl.custom.inlineresult.InlineResult>`.
|
||||
|
||||
Example
|
||||
.. code-block:: python
|
||||
|
||||
# Make an inline query to @like
|
||||
results = await client.inline_query('like', 'Do you like Telethon?')
|
||||
|
||||
# Send the first result to some chat
|
||||
message = await results[0].click('TelethonOffTopic')
|
||||
"""
|
||||
bot = await self.get_input_entity(bot)
|
||||
if entity:
|
||||
peer = await self.get_input_entity(entity)
|
||||
else:
|
||||
peer = types.InputPeerEmpty()
|
||||
|
||||
result = await self(functions.messages.GetInlineBotResultsRequest(
|
||||
bot=bot,
|
||||
peer=peer,
|
||||
peer=types.InputPeerEmpty(),
|
||||
query=query,
|
||||
offset=offset or '',
|
||||
geo_point=geo_point
|
||||
))
|
||||
|
||||
return custom.InlineResults(self, result, entity=peer if entity else None)
|
||||
return custom.InlineResults(self, result)
|
||||
|
|
|
|||
|
|
@ -1,42 +1,20 @@
|
|||
import typing
|
||||
|
||||
from .. import utils, hints
|
||||
from .updates import UpdateMethods
|
||||
from ..tl import types, custom
|
||||
from .. import utils, events
|
||||
|
||||
|
||||
class ButtonMethods:
|
||||
@staticmethod
|
||||
def build_reply_markup(
|
||||
buttons: 'typing.Optional[hints.MarkupLike]',
|
||||
inline_only: bool = False) -> 'typing.Optional[types.TypeReplyMarkup]':
|
||||
class ButtonMethods(UpdateMethods):
|
||||
def build_reply_markup(self, buttons, inline_only=False):
|
||||
"""
|
||||
Builds a :tl:`ReplyInlineMarkup` or :tl:`ReplyKeyboardMarkup` for
|
||||
the given buttons.
|
||||
Builds a :tl`ReplyInlineMarkup` or :tl:`ReplyKeyboardMarkup` for
|
||||
the given buttons, or does nothing if either no buttons are
|
||||
provided or the provided argument is already a reply markup.
|
||||
|
||||
Does nothing if either no buttons are provided or the provided
|
||||
argument is already a reply markup.
|
||||
|
||||
You should consider using this method if you are going to reuse
|
||||
the markup very often. Otherwise, it is not necessary.
|
||||
|
||||
This method is **not** asynchronous (don't use ``await`` on it).
|
||||
|
||||
Arguments
|
||||
buttons (`hints.MarkupLike`):
|
||||
The button, list of buttons, array of buttons or markup
|
||||
to convert into a markup.
|
||||
|
||||
inline_only (`bool`, optional):
|
||||
Whether the buttons **must** be inline buttons only or not.
|
||||
|
||||
Example
|
||||
.. code-block:: python
|
||||
|
||||
from telethon import Button
|
||||
|
||||
markup = client.build_reply_markup(Button.inline('hi'))
|
||||
# later
|
||||
await client.send_message(chat, 'click me', buttons=markup)
|
||||
This will add any event handlers defined in the
|
||||
buttons and delete old ones not to call them twice,
|
||||
so you should probably call this method manually for
|
||||
serious bots instead re-adding handlers every time you
|
||||
send a message. Magic can only go so far.
|
||||
"""
|
||||
if buttons is None:
|
||||
return None
|
||||
|
|
@ -49,29 +27,17 @@ class ButtonMethods:
|
|||
|
||||
if not utils.is_list_like(buttons):
|
||||
buttons = [[buttons]]
|
||||
elif not buttons or not utils.is_list_like(buttons[0]):
|
||||
elif not utils.is_list_like(buttons[0]):
|
||||
buttons = [buttons]
|
||||
|
||||
is_inline = False
|
||||
is_normal = False
|
||||
resize = None
|
||||
single_use = None
|
||||
selective = None
|
||||
|
||||
rows = []
|
||||
for row in buttons:
|
||||
current = []
|
||||
for button in row:
|
||||
if isinstance(button, custom.Button):
|
||||
if button.resize is not None:
|
||||
resize = button.resize
|
||||
if button.single_use is not None:
|
||||
single_use = button.single_use
|
||||
if button.selective is not None:
|
||||
selective = button.selective
|
||||
|
||||
button = button.button
|
||||
elif isinstance(button, custom.MessageButton):
|
||||
if isinstance(button, custom.MessageButton):
|
||||
button = button.button
|
||||
|
||||
inline = custom.Button._is_inline(button)
|
||||
|
|
@ -91,6 +57,5 @@ class ButtonMethods:
|
|||
raise ValueError('You cannot mix inline with normal buttons')
|
||||
elif is_inline:
|
||||
return types.ReplyInlineMarkup(rows)
|
||||
# elif is_normal:
|
||||
return types.ReplyKeyboardMarkup(
|
||||
rows, resize=resize, single_use=single_use, selective=selective)
|
||||
elif is_normal:
|
||||
return types.ReplyKeyboardMarkup(rows)
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load Diff
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue
Block a user