Release notes for python-telegram-bot v20.0a0
PTB development teamHere it is: The long awaitedasyncio
pre-release.
⚠️ This is a pre-release. We do not recommend to use it in production.
First things first: We want to sincerely thank everyone who contributed to this release, be it in form of code contributions, feature requests, bug reports, discussions, advice or encouraging comments. We also want to thank all users for their patience. The development time for this release hasn't exactly been short, but we are confident that it was worth it 🙂
Now, let us talk changes. The most important and most disrupting change is clearly the asyncio
rewrite of python-telegram-bot
. All networking and I/O related logic now works via coroutine functions (i.e. async def ...
functions). In particular, all methods of the telegram.Bot
class that make requests to the Bot API are now coroutine functions and need to be await
-ed. One notable decision that we made during the development progress is that all handler/job callbacks have to be coroutine functions as well. Defining callbacks as def callback(update, context)
will hence no longer work. We had several discussions in the development team before making this decision, but ultimately decided for this breaking change due to several reasons:
- Coroutine functions can readily call regular functions. In case your callback doesn't need any
asyncio
logic, theasync def
should be at most a minor inconvenience. - Using blocking functions in an
asyncio
code base lowers performance significantly. If you e.g. currently use something liketime.sleep(x)
in your callbacks, you should rework that callback anyway. - Transitioning your code base to the new version will be notably more work than transitions between previous major releases. Typing
async
a few times doesn't matter much.
We hope that with the new, asyncio
-based python-telegram-bot
, leveraging concurrency will be easier for you.
During the development process of this release and especially while working on the asyncio
part, we realized that parts of the current design of the library are not optimal. We took the opportunity to take a step back, reevaluate the designs and change them where necessary. As a result, several structural changes have been made to the library. Most notably, the Dispatcher
class was removed. Instead, there is a new Application
class, which serves as the entry point to a PTB bot and manages all the different components like Updater
, JobQueue
, Bot
etc. Another change is the networking backend of PTB, which was reworked to the all new and customizable telegram.request
module. Noteworthy is also that the telegram.ext.filters
module has been reworked thoroughly in terms of namespaces and naming conventions. This was done to reflect the fact that filters have been purely class-based since v12.
We should also not forget to mention that a number of features were removed. The largest part of removed features is the non-context-based handler API, which was deprecated in v12. Moreover, the MessageQueue
was removed after it had been deprecated in v13.3. While this pre-release does not yet include an alternative mechanism to avoid flood limits, this is on our roadmap.
Apart from all the changes in the functionality/interface, we have also spent some time on improving the internals of PTB. We put effort into making it more clear which parts of python-telegram-bot
can be considered the public interface that users are allowed to use and which are private modules, increased the code quality and extended unit tests. All those improvements will hopefully help to ease future maintenance work, which in turn greatly benefits the quality of new library versions.
In addition to all the changes, this release also brings some new functionality. Most notably, it includes support for Bot API 6.0. Note that all parameters, attributes and classes with voice_chat
/VoiceChat
in their name have been renamed to video_chat
/VideoChat
in order to comply with the Bot API update. Also note that after the next API update, only HTTPS links will be allowed in the login_url
argument of InlineKeyboardButton
.
Finally, the look and feel of our documentation has been greatly improved. It uses a new theme, supports dark mode, is mobile friendly, has more cross-reference links, including a direct link to source code for each item, and much more! You can check it out here.
In addition to these release notes and the below changelog, we have prepared an elaborate transition guide. In case you want to try out this pre-release, please be sure to both read that guide and to check out the relevant updated wiki pages that it links to. The transition guide also includes a transition scripts that can help to ease the transition.
We have gathered some questions we expect you to have below and answered them directly. Please make sure to read them before asking a question in the support group, just in case we already covered it.
Otherwise have a lovely time with the library! Sincerely,
The PTB development team
How do I install this release?
By default, pip
does not install pre-releases. If you want to try out this release, install it via pip install -U python-telegram-bot --pre
.
Wasn't it supposed to be v14 instead of v20?
Yes. We decided to bump the version number more notably to emphasize the big structural changes that this release brings.
What is a pre-release? What does the a0 in the version number mean?
The idea of pre-releases is to publish software that is not quite ready yet but ready enough to be tested. Pre-releases help to e.g. get feedback from users discover bugs. As such, we advice not to use this pre-release in production. If you want to try v20.0a0 out, please do that with a project that you are prepared to monitor closely.
The a0
is a shorthand for "alpha 0", i.e. the first alpha release for v20.0. In the alpha state, new versions may introduce new breaking changes, so a version v20.0a1 may introduce changes that are not backwards compatible to v20.0a0.
What's next for v20?
It will still take a bit until v20 get's a stable release. We have some more changes on our roadmap, some of which will still be breaking. None of them will however be as disruptive as the changes included in this pre-release. We expect to make a few more alpha and beta releases until v20 is mature enough for a stable release.
What's planned for v13?
As of now, v13 is already in a "Bot API compatibility mode", i.e. the last few v13.x releases contained exclusively Bot API updates. We are positively considering to maintain this mode until v20 has a first stable release and backport any Bot API updates to v13. The backports may take more time than the updates for v20. If the development team has too few resources or the updates are too big, we may have to abandon API updates for v13 in favour of advancing development of v20.
Can I use v20 without asyncio?
No. As explained in our original announcement from January 2021, we did not add a compatibility layer.
I'm not familiar with asyncio. Can you give an introduction?
asyncio
is a modern alternative to threading
that comes with multiple advantages. Covering those or an introduction to how using asyncio
works, is sadly beyond the scope of the PTB resources. Searching for python asyncio introduction
or python asyncio vs threading
in your favorite search engine will yield numerous results that will help you get up to speed.
Can I help improving v20?
Yes!
You can take v20.0a0 up for a test run. If you encounter any issues (either unexpected warnings, error messages or just problems with figuring out how to write code with the new version), please don't hesitate to let us know.
In particular, running PTB under different networking conditions is hard to test for us. If you're running PTB behind a proxy, Socks5 proxy, with a custom webhook setup or some other special case, it would be great if you could test if this release works for your setting.
You can even help us by making code contributions yourself! Some of the items on the roadmap are well suited for first-time and novice contributors. We aim to provide information on suitable tasks in the development group in the near future.
Changelog
Major Changes:
- Refactor Initialization of Persistence Classes (#2604)
- Drop Non-
CallbackContext
API (#2617) - Remove
__dict__
from__slots__
and drop Python 3.6 (#2619, #2636) - Move and Rename
TelegramDecryptionError
totelegram.error.PassportDecryptionError
(#2621) - Make
BasePersistence
Methods Abstract (#2624) - Remove
day_is_strict
argument ofJobQueue.run_monthly
(#2634 by iota-008) - Move
Defaults
totelegram.ext
(#2648) - Remove Deprecated Functionality (#2644, #2740, #2745)
- Overhaul of Filters (#2759, #2922)
- Switch to
asyncio
and Refactor PTBs Architecture (#2731) - Improve
Job.__getattr__
(#2832) - Remove
telegram.ReplyMarkup
(#2870) - Persistence of
Bots
: Refactor Automatic Replacement and Integration withTelegramObject
(#2893)
New Features:
- Introduce Builder Pattern (#2646)
- Add
Filters.update.edited
(#2705 by PhilippFr) - Introduce
Enums
fortelegram.constants
(#2708) - Accept File Paths for
private_key
(#2724) - Associate
Jobs
withchat/user_id
(#2731) - Convenience Functionality for
ChatInviteLinks
(#2782) - Add
Dispatcher.add_handlers
(#2823) - Improve Error Messages in
CommandHandler.__init__
(#2837) Defaults.protect_content
(#2840)- Add
Dispatcher.migrate_chat_data
(#2848 by DonalDuck004) - Add Method
drop_chat/user_data
toDispatcher
and Persistence (#2852) - Add methods
ChatPermissions.{all, no}_permissions
(#2948) - Full Support for API 6.0 (#2956)
- Add Python 3.10 to Test Suite (#2968)
Bug Fixes & Minor Changes:
- Improve Type Hinting for
CallbackContext
(#2587 by revolter) - Fix Signatures and Improve
test_official
(#2643) - Refine
Dispatcher.dispatch_error
(#2660) - Make
InlineQuery.answer
RaiseValueError
(#2675) - Improve Signature Inspection for Bot Methods (#2686)
- Introduce
TelegramObject.set/get_bot
(#2712 by zpavloudis) - Improve Subscription of
TelegramObject
(#2719 by SimonDamberg) - Use Enums for Dynamic Types & Rename Two Attributes in
ChatMember
(#2817) - Return Plain Dicts from
BasePersistence.get_*_data
(#2873) - Fix a Bug in
ChatMemberUpdated.difference
(#2947) - Update Dependency Policy (#2958)
Internal Restructurings & Improvements:
- Add User Friendly Type Check For Init Of
{Inline, Reply}KeyboardMarkup
(#2657) - Warnings Overhaul (#2662)
- Clear Up Import Policy (#2671)
- Mark Internal Modules As Private (#2687 by kencx)
- Handle Filepaths via the
pathlib
Module (#2688 by eldbud) - Refactor MRO of
InputMedia*
and Some File-Like Classes (#2717 by eldbud) - Update Exceptions for Immutable Attributes (#2749)
- Refactor Warnings in
ConversationHandler
(#2755, #2784) - Use
__all__
Consistently (#2805)
CI, Code Quality & Test Suite Improvements:
- Add Custom
pytest
Marker to Ease Development (#2628) - Pass Failing Jobs to Error Handlers (#2692)
- Update Notification Workflows (#2695)
- Use Error Messages for
pylint
Instead of Codes (#2700 by Piraty) - Make Tests Agnostic of the CWD (#2727 by eldbud)
- Update Code Quality Dependencies (#2748)
- Improve Code Quality (#2783)
- Update
pre-commit
Settings & Improve a Test (#2796) - Improve Code Quality & Test Suite (#2843)
- Fix failing animation tests (#2865)
- Update and Expand Tests & pre-commit Settings and Improve Code Quality (#2925)
- Extend Code Formatting With Black (#2972)
- Update Workflow Permissions (#2984)
- Adapt Tests to Changed
Bot.get_file
Behavior (#2995)
Documentation Improvements:
- Doc Fixes (#2597)
- Add Code Comment Guidelines to Contribution Guide (#2612)
- Add Cross-References to External Libraries & Other Documentation Improvements (#2693, #2691 by joesinghh, #2739 by eldbud)
- Use Furo Theme, Make Parameters Referenceable, Add Documentation Building to CI, Improve Links to Source Code & Other Improvements (#2856, #2798, #2854, #2841)
- Documentation Fixes & Improvements (#2822)
- Replace
git.io
Links (#2872 by murugu-21) - Overhaul Readmes, Update RTD Startpage & Other Improvements (#2969)