mirror of
https://github.com/LonamiWebs/Telethon.git
synced 2024-11-10 19:46:36 +03:00
125 lines
5.0 KiB
Markdown
125 lines
5.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.
|
|
|
|
### [`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
|
|
[`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
|