Installation¶
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:
You can also install the library directly from GitHub or a fork:
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 via pip or as an extra:
Manual Installation¶
Install the required pyaes (GitHub | PyPi) and rsa (GitHub | PyPi) modules:
sudo -H pip3 install pyaes rsa
Clone Telethon’s GitHub repository: git clone https://github.com/LonamiWebs/Telethon.git
Enter the cloned repository: cd Telethon
Run the code generator: python3 setup.py gen_tl
To generate the method documentation, cd docs and then python3 generate.py (if some pages render bad do it twice).
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.
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:
…to install or upgrade the library to the latest version.
Installing Development Versions¶
If you want the latest unreleased changes, you can run the following command instead:
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.
Verification¶
To verify that the library is installed correctly, run the following command:
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 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.
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 ):
Telethon 1.25.2
⭐️ Thanks everyone who has starred the project, it means a lot!
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).
If you have code using Telethon before its 1.0 version, you must read Compatibility and Convenience to learn how to migrate.
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 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.
Installing
Creating a client
Doing stuff
Next steps
Do you like how Telethon looks? Check out Read The Docs for a more in-depth explanation, with examples, troubleshooting issues, and more useful information.
einali/Telethon
Telethon is Telegram client implementation in Python which uses the latest available API of Telegram.
Before opening an issue about how to use the library, please make sure you have read and followed the steps mentioned under Using Telethon and are using the latest version! A lot of people ask simple questions which will only be answered as «please see the README.rst «. And you should use the search before posting an issue, too.
If you come here often, you may want to go to the docs.
Table of contents
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 entirely on Python, Telethon can run as a script under any environment you wish, (yes, Android too). 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.
Hungry for more API calls which the TelegramClient class doesn’t seem to have implemented? Please read Using more than just TelegramClient.
In order to use Telethon, you first need to obtain your very own API ID and Hash:
- Follow this link and login with your phone number.
- Click under API Development tools.
- 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.
- Click on Create application at the end.
Now that you know your API ID and Hash , you can continue installing Telethon.
On a terminal, issue the following command:
You’re ready to go. Oh, and upgrading is just as easy:
- Install the required pyaes module: sudo -H pip install pyaes (GitHub, package index)
- Clone Telethon’s GitHub repository: git clone https://github.com/LonamiWebs/Telethon.git
- Enter the cloned repository: cd Telethon
- Run the code generator: python3 setup.py gen_tl
- Done!
If you’ve installed Telethon via pip, launch an interactive python3 session and enter the following:
If, on the other hand, you’ve installed Telethon manually, head to the 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).
Then, simply run ./try_telethon.py to start the interactive example.
If you really want to learn how to use Telethon, it is highly advised that you take a look to the InteractiveTelegramClient file and check how it works. This file contains everything you’ll need to build your own application, since it shows, among other things:
- Authorizing the user for the first time.
- Support to enter the 2-steps-verification code.
- Retrieving dialogs (chats) and the messages history.
- Sending messages and files.
- Downloading files.
- Updates thread.
If you want a nicer way to see all the available requests and types at your disposal, please check the official Telethon documentation. There you’ll find a list of all the methods, types and available constructors.
More examples are also available under the telethon_examples/ folder.
Errors resulting from Telegram queries all subclass the RPCError class. This class is further specialized into further errors:
- 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!
- FloodError (420), the same request was repeated many times. Must wait .seconds .
Further specialization is also available, for instance, the SessionPasswordNeededError when signing in means that a password must be provided to continue.
If the error is not recognised, it will only be an RPCError .
Unless you know what you’re doing, you should download media by always using the .download_file() function, which supports a str or a file handle as parameters. Otherwise, .invoke() may raise InvalidDCError which you will have to handle, and in turn call .invoke_on_dc() manually.
The TelegramClient class should be used to provide a quick, well-documented and simplified starting point. It is not meant to be a place for all the available Telegram Request ‘s, because there are simply too many.
However, this doesn’t mean that you cannot invoke all the power of Telegram’s API. Whenever you need to call a Telegram Request , all you need to do is the following:
You have just called SomeRequest and retrieved its result ! That wasn’t hard at all, was it? Now you may wonder, what’s the deal with all the power of Telegram’s API? Have a look under tl/functions/ . That is everything you can do. You have over 200 API Request ‘s at your disposal.
However, we don’t pretty know how that result looks like. Easy. print(str(result)) should give you a quick overview. Nevertheless, there may be more than a single result ! Let’s have a look at this seemingly innocent TL definition:
messages.getWebPagePreview#25223e24 message:string = MessageMedia;
Focusing on the end, we can see that the result of invoking GetWebPagePreviewRequest is MessageMedia . But how can MessageMedia exactly look like? It’s time to have another look, but this time under tl/types/ :
Those are eight different types! How do we know what exact type it is to determine its properties? A simple if type(result) == MessageMediaContact: or similar will do. Now you’re ready to take advantage of Telegram’s polymorphism.
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, start by looking at the first release 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!
The code generator will skip the types considered as core types. These types are usually included in almost every programming language, such as boolean values or lists, and also the Telegram True flag, which is not sent but rather used to determine whether that flag should be enabled or not.
Have you found a more updated version of the scheme.tl file? Those are great news! Updating is as simple as grabbing the latest version and replacing the one you can find in this same directory by the updated one. Don’t forget to run python3 setup.py gen_tl .
If the changes weren’t too big, everything should still work the same way as it did before; but with extra features.
If you want to use Telethon via proxy, you have to install PySocks (via pip or manual). Once this is done, pass the proxy settings to the TelegramClient constructor:
The proxy= argument should be a tuple, a list or a dict, consisting of parameters described here.
Project Statistics
| Sourcerank | 3 |
| Repository Size | 1.4 MB |
| Stars | 0 |
| Forks | 0 |
| Watchers | 1 |
| Open issues | disabled |
| Dependencies | 1 |
| Tags | 19 |
| Created | Jul 12, 2017 |
| Last updated | Jul 12, 2017 |
| Last pushed | Jul 12, 2017 |
Recent Tags See all
| v0.11.5 | July 11, 2017 |
| v0.11.4 | July 10, 2017 |
| v0.11.3 | July 04, 2017 |
| v0.11.2 | July 04, 2017 |
| v0.11.1 | June 24, 2017 |
| v0.11 | June 16, 2017 |
| v0.10.1 | June 07, 2017 |
| v0.10 | June 03, 2017 |
| v0.9.1 | May 23, 2017 |
| v0.9 | May 19, 2017 |
| v0.8 | April 14, 2017 |
| v0.7.1 | February 19, 2017 |
| v0.7 | January 30, 2017 |
| v0.6 | November 13, 2016 |
| v0.5 | September 18, 2016 |
Something wrong with this page? Make a suggestion
Last synced: 2017-07-18 13:24:15 UTC
Login to resync this repository
Libraries.io helps you find new open source packages, modules and frameworks and keep track of ones you depend upon.
Copyright © 2022 Tidelift, Inc
Code is Open Source under AGPLv3 license
Data is available under CC-BY-SA 4.0 license