mirror of
https://github.com/LonamiWebs/Telethon.git
synced 2024-11-10 19:46:36 +03:00
Updated README.md
This commit is contained in:
parent
72bc9df683
commit
0068c0fd8b
2
LICENSE
2
LICENSE
|
@ -1,6 +1,6 @@
|
|||
MIT License
|
||||
|
||||
Copyright (c) [year] [fullname]
|
||||
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
|
||||
|
|
64
README.md
64
README.md
|
@ -6,6 +6,33 @@ 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
|
||||
|
@ -22,13 +49,14 @@ can be changed later as long as I'm aware.
|
|||
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
|
||||
## 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.
|
||||
|
||||
## How to add more functions to TelegramClient
|
||||
## 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,
|
||||
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:
|
||||
|
||||
|
@ -55,12 +83,29 @@ open the file and see what the result will look like. Alternatively, you can sim
|
|||
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.
|
||||
|
||||
## Plans for the future
|
||||
If everything works well, this probably ends up being a Python package :)
|
||||
_Hint: You could even write your own class based on `TelegramClient` and add more features._
|
||||
|
||||
But as of now, and until that happens, help is highly appreciated!
|
||||
### 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:
|
||||
|
||||
## Code generator limitations
|
||||
`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.).
|
||||
|
||||
|
@ -77,3 +122,8 @@ In order to make sure that all the generated files will work, please make sure 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!
|
||||
|
|
Loading…
Reference in New Issue
Block a user