Release notes for python-telegram-bot v20.0a0

Release notes for python-telegram-bot v20.0a0

PTB development team

Here 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, the async 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 like time.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 to telegram.error.PassportDecryptionError (#2621)
  • Make BasePersistence Methods Abstract (#2624)
  • Remove day_is_strict argument of JobQueue.run_monthly (#2634 by iota-008)
  • Move Defaults to telegram.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 with TelegramObject (#2893)

New Features:

  • Introduce Builder Pattern (#2646)
  • Add Filters.update.edited (#2705 by PhilippFr)
  • Introduce Enums for telegram.constants (#2708)
  • Accept File Paths for private_key (#2724)
  • Associate Jobs with chat/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 to Dispatcher 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 Raise ValueError (#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)
Report content on this page

Report Page

Please submit your DMCA takedown request to dmca@telegram.org