mirror of
https://github.com/LonamiWebs/Telethon.git
synced 2024-09-21 03:08:49 +03:00
130 lines
7.2 KiB
Markdown
Executable File
130 lines
7.2 KiB
Markdown
Executable File
# Telethon
|
|
**Telethon** is Telegram client implementation in Python. This project's _core_ is **completely based** on
|
|
[TLSharp](https://github.com/sochix/TLSharp). All the files which are fully based on it will have a notice
|
|
on the top of the file. Also don't forget to have a look to the original project.
|
|
|
|
The files without the previously mentioned notice are no longer part of TLSharp itself, or have enough modifications
|
|
to make them entirely different.
|
|
|
|
# Table of contents
|
|
- [Why Telethon?](#why-telethon)
|
|
- [Requirements](#requirements)
|
|
- [Python modules](#python-modules)
|
|
- [Obtaining your `API ID` and `Hash`](#obtaining-your-api-id-and-hash)
|
|
- [Running Telethon](#running-telethon)
|
|
- [Advanced uses](#advanced-uses)
|
|
- [How to add more functions to `TelegramClient`](#how-to-add-more-functions-to-telegramclient)
|
|
- [Tips for porting Telethon](#tips-for-porting-telethon)
|
|
- [Code generator limitations](#code-generator-limitations)
|
|
- [Plans for the future](#plans-for-the-future)
|
|
|
|
## Why Telethon?
|
|
> Why should I bother with Telethon? You already mentioned [TLSharp](https://github.com/sochix/TLSharp).
|
|
> [telegram-cli](https://github.com/vysheng/tg) has also been around for a long while. And we have the
|
|
> [official](https://github.com/telegramdesktop/tdesktop) [clients](https://github.com/DrKLO/Telegram)!
|
|
|
|
With Telethon you don't really need to know anything before using it. Create a client with your settings.
|
|
Connect. You're ready to go.
|
|
|
|
Being written on Python, Telethon can run as a script under any environment you wish, (yes,
|
|
[Android too](https://f-droid.org/repository/browse/?fdfilter=termux&fdid=com.termux)). You can schedule it,
|
|
or use it in any other script you have. Want to send a message to someone when you're available? Write a script.
|
|
Do you want check for new messages at a given time and find relevant ones? Write a script.
|
|
|
|
An official client has a feature which Telethon doesn't? [Implement it easily](#how-to-add-more-functions-to-telegramclient).
|
|
|
|
## Requirements
|
|
### Python modules
|
|
This project requires the following Python modules, which can be installed by issuing `sudo -H pip3 install <module>` on a
|
|
Linux terminal:
|
|
- `pyaes` ([GitHub](https://github.com/ricmoo/pyaes), [package index](https://pypi.python.org/pypi/pyaes))
|
|
|
|
### Obtaining your `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 be changed later as long as I'm aware.
|
|
4. Click on `Create application` at the end. Now that you have the `API ID` and `Hash`,
|
|
head to `api/` directory and create a copy of the `settings_example` file, naming it `settings` (lowercase!).
|
|
Then fill the file with the corresponding values (your `api_id`, `api_hash` and phone number in international format).
|
|
|
|
## Running Telethon
|
|
First of all, you need to run the `tl_generator.py` by issuing `python3 tl_generator.py`. This will generate all the
|
|
TLObjects from the given `scheme.tl` file. When it's done, you can run `python3 main.py` to start the interactive example.
|
|
|
|
## Advanced uses
|
|
### How to add more functions to `TelegramClient`
|
|
As of now, you cannot call any Telegram function unless you first write it by hand under `tl/telegram_client.py`. Why?
|
|
Every Telegram function (or _Request_) work in its own way. In some, you may only be interested in a single result field,
|
|
and in others you may need to format the result in a different way. However, a plan for the future is to be able to call
|
|
any function by giving its `namespace.name` and passing the arguments. But until that happens, to add a new function do:
|
|
|
|
1. Have a look under `tl/functions/` and find the `Request` that suits your needs.
|
|
2. Have a look inside that `Request` you chose, and find what arguments and in what order you'll need to call it.
|
|
3. Import it in `tl/telegram_client.py` by using `from tl.functions import SomeTelegramRequest`.
|
|
4. Add a new method, or function, that looks as follows:
|
|
```python
|
|
def my_function(self, my_arguments):
|
|
request = SomeTelegramRequest(my_arguments)
|
|
|
|
self.sender.send(request)
|
|
self.sender.receive(request)
|
|
|
|
return request.result
|
|
```
|
|
To determine how the result will look like, simply look at the original `.tl` definition. After the `=`,
|
|
you will see the type. Let's see an example:
|
|
`stickerPack#12b299d4 emoticon:string documents:Vector<long> = StickerPack;`
|
|
|
|
As it turns out, the result is going to be an `StickerPack`. Without a second doubt, head into `tl/types/` and find it;
|
|
open the file and see what the result will look like. Alternatively, you can simply `print(str(request.result))`!
|
|
|
|
Be warned that there may be more than one different type on the results. This is due to Telegram's polymorphism,
|
|
for example, a message may or not be empty, etc.
|
|
|
|
_Hint: You could even write your own class based on `TelegramClient` and add more features._
|
|
|
|
### Tips for porting Telethon
|
|
First of all, you need to understand how the `scheme.tl` (`TL` language) works. Every object definition is written as follows:
|
|
|
|
`name#id argument_name:argument_type = CommonType`
|
|
|
|
This means that in a single line you know what the `TLObject` name is. You know it's unique ID,
|
|
and you know what arguments it has. It really isn't that hard to write a generator for generating code to any platform!
|
|
|
|
The generated code should also be able to _encode_ the `Request` into bytes, so they can be sent over the network.
|
|
This isn't a big deal either, because you know how the `TLObject`'s are made.
|
|
|
|
Once you have your own [code generator](tl_generator.py), start by looking at the
|
|
[first release](https://github.com/LonamiWebs/Telethon/releases/tag/v0.1) of Telethon.
|
|
The code there is simple to understand, easy to read and hence easy to port. No extra useless features.
|
|
Only the bare bones. Perfect for starting a _new implementation_.
|
|
|
|
P.S.: I may have lied a bit. The `TL` language is not that easy. But it's not that hard either.
|
|
You're free to sniff the `parser/` files and learn how to parse other more complex lines.
|
|
Or simply use that code and change the [SourceBuilder](parser/source_builder.py)!
|
|
|
|
### Code generator limitations
|
|
The current code generator is not complete, yet adding the missing features would only over-complicate an already hard-to-read code.
|
|
Some parts of the `.tl` file _should_ be omitted, because they're "built-in" in the generated code (such as writing booleans, etc.).
|
|
|
|
In order to make sure that all the generated files will work, please make sure to **always** comment out these lines in `scheme.tl`
|
|
(the latest version can always be found
|
|
[here](https://github.com/telegramdesktop/tdesktop/blob/master/Telegram/SourceFiles/mtproto/scheme.tl)):
|
|
|
|
```tl
|
|
// boolFalse#bc799737 = Bool;
|
|
// boolTrue#997275b5 = Bool;
|
|
// true#3fedd339 = True;
|
|
// vector#1cb5c415 {t:Type} # [ t ] = Vector t;
|
|
```
|
|
|
|
Also please make sure to rename `updates#74ae4240 ...` to `updates_tg#74ae4240 ...` or similar to avoid confusion between
|
|
the `updates` folder and the `updates.py` file!
|
|
|
|
## Plans for the future
|
|
If everything works well, this probably ends up being a Python package :)
|
|
|
|
But as of now, and until that happens, help is highly appreciated!
|