mirror of
https://github.com/LonamiWebs/Telethon.git
synced 2024-11-26 11:23:46 +03:00
150 lines
6.0 KiB
Markdown
150 lines
6.0 KiB
Markdown
# Examples
|
|
|
|
This folder contains several single-file examples using [Telethon].
|
|
|
|
## Requisites
|
|
|
|
You should have the `telethon` library installed with `pip`.
|
|
Run `python3 -m pip install --upgrade telethon --user` if you don't
|
|
have it installed yet (this is the most portable way to install it).
|
|
|
|
The scripts will ask you for your API ID, hash, etc. through standard input.
|
|
You can also define the following environment variables to avoid doing so:
|
|
|
|
* `TG_API_ID`, this is your API ID from https://my.telegram.org.
|
|
* `TG_API_HASH`, this is your API hash from https://my.telegram.org.
|
|
* `TG_TOKEN`, this is your bot token from [@BotFather] for bot examples.
|
|
* `TG_SESSION`, this is the name of the `*.session` file to use.
|
|
|
|
## Downloading Examples
|
|
|
|
You may download all and run any example by typing in a terminal:
|
|
```sh
|
|
git clone https://github.com/LonamiWebs/Telethon.git
|
|
cd Telethon
|
|
cd telethon_examples
|
|
python3 gui.py
|
|
```
|
|
|
|
You can also right-click the title of any example and use "Save Link As…" to
|
|
download only a particular example.
|
|
|
|
All examples are licensed under the [CC0 License], so you can use
|
|
them as the base for your own code without worrying about copyright.
|
|
|
|
## Available Examples
|
|
|
|
### [`print_updates.py`]
|
|
|
|
* Usable as: **user and bot**.
|
|
* Difficulty: **easy**.
|
|
|
|
Trivial example that just prints all the updates Telegram originally
|
|
sends. Your terminal should support UTF-8, or Python may fail to print
|
|
some characters on screen.
|
|
|
|
### [`print_messages.py`]
|
|
|
|
* Usable as: **user and bot**.
|
|
* Difficulty: **easy**.
|
|
|
|
This example uses the different `@client.on` syntax to register event
|
|
handlers, and uses the `pattern=` variable to filter only some messages.
|
|
|
|
There are a lot other things you can do, but you should refer to the
|
|
documentation of [`events.NewMessage`] since this is only a simple example.
|
|
|
|
### [`replier.py`]
|
|
|
|
* Usable as: **user and bot**.
|
|
* Difficulty: **easy**.
|
|
|
|
This example showcases a third way to add event handlers (using decorators
|
|
but without the client; you should use the one you prefer) and will also
|
|
reply to some messages with different reactions, or to your commands.
|
|
|
|
It also shows how to enable `logging`, which you should always do, but was
|
|
not really needed for the previous two trivial examples.
|
|
|
|
### [`assistant.py`]
|
|
|
|
* Usable as a: **bot**.
|
|
* Difficulty: **medium**.
|
|
|
|
This example is the actual bot account [@TelethonianBot] running in the
|
|
[official Telethon's chat] to help people out. The file is a bit big and
|
|
assumes some [`asyncio`] knowledge, but otherwise is easy to follow.
|
|
|
|
In addition, it has optional plugins, which may be useful for your own code.
|
|
The plugins can be found at https://github.com/Lonami/TelethonianBotExt and
|
|
should be cloned into a `plugins` folder next to `assistant.py` for them to
|
|
work.
|
|
|
|
### [`interactive_telegram_client.py`]
|
|
|
|
* Usable as: **user**.
|
|
* Difficulty: **medium**.
|
|
|
|
Interactive terminal client that you can use to list your dialogs,
|
|
send messages, delete them, and download media. The code is a bit
|
|
long which may make it harder to follow, and requires saving some
|
|
state in order for downloads to work later.
|
|
|
|
### [`quart_login.py`]
|
|
|
|
* Usable as: **user**.
|
|
* Difficulty: **medium**.
|
|
|
|
Web-based application using [Quart](https://pgjones.gitlab.io/quart/index.html)
|
|
(an `asyncio` alternative to [Flask](http://flask.pocoo.org/)) and Telethon
|
|
together.
|
|
|
|
The example should work as a base for Quart applications *with a single
|
|
global client*, and it should be easy to adapt for multiple clients by
|
|
following the comments in the code.
|
|
|
|
It showcases how to login manually (ask for phone, code, and login),
|
|
and once the user is logged in, some messages and photos will be shown
|
|
in the page.
|
|
|
|
There is nothing special about Quart. It was chosen because it's a
|
|
drop-in replacement for Flask, the most popular option for web-apps.
|
|
You can use any `asyncio` library with Telethon just as well,
|
|
like [Sanic](https://sanic.readthedocs.io/en/latest/index.html) or
|
|
[aiohttp](https://docs.aiohttp.org/en/stable/). You can even use Flask,
|
|
if you learn how to use `threading` and `asyncio` together.
|
|
|
|
### [`gui.py`]
|
|
|
|
* Usable as: **user and bot**.
|
|
* Difficulty: **high**.
|
|
|
|
This is a simple GUI written with [`tkinter`] which becomes more complicated
|
|
when there's a need to use [`asyncio`] (although it's only a bit of additional
|
|
setup). The code to deal with the interface and the commands the GUI supports
|
|
also complicate the code further and require knowledge and careful reading.
|
|
|
|
This example is the actual bot account [@TelethonianBot] running in the
|
|
[official Telethon's chat] to help people out. The file is a bit big and
|
|
assumes some [`asyncio`] knowledge, but otherwise is easy to follow.
|
|
|
|
![Screenshot of the tkinter GUI][tkinter GUI]
|
|
|
|
|
|
[Telethon]: https://github.com/LonamiWebs/Telethon
|
|
[CC0 License]: https://github.com/LonamiWebs/Telethon/blob/master/telethon_examples/LICENSE
|
|
[@BotFather]: https://t.me/BotFather
|
|
[`assistant.py`]: https://raw.githubusercontent.com/LonamiWebs/Telethon/master/telethon_examples/assistant.py
|
|
[`quart_login.py`]: https://raw.githubusercontent.com/LonamiWebs/Telethon/master/telethon_examples/quart_login.py
|
|
[`gui.py`]: https://raw.githubusercontent.com/LonamiWebs/Telethon/master/telethon_examples/gui.py
|
|
[`interactive_telegram_client.py`]: https://raw.githubusercontent.com/LonamiWebs/Telethon/master/telethon_examples/interactive_telegram_client.py
|
|
[`print_messages.py`]: https://raw.githubusercontent.com/LonamiWebs/Telethon/master/telethon_examples/print_messages.py
|
|
[`print_updates.py`]: https://raw.githubusercontent.com/LonamiWebs/Telethon/master/telethon_examples/print_updates.py
|
|
[`replier.py`]: https://raw.githubusercontent.com/LonamiWebs/Telethon/master/telethon_examples/replier.py
|
|
[@TelethonianBot]: https://t.me/TelethonianBot
|
|
[official Telethon's chat]: https://t.me/TelethonChat
|
|
[`asyncio`]: https://docs.python.org/3/library/asyncio.html
|
|
[`tkinter`]: https://docs.python.org/3/library/tkinter.html
|
|
[tkinter GUI]: https://raw.githubusercontent.com/LonamiWebs/Telethon/master/telethon_examples/screenshot-gui.jpg
|
|
[`events.NewMessage`]: https://docs.telethon.dev/en/latest/modules/events.html#telethon.events.newmessage.NewMessage
|