So I've had this idea brewing in my head and was also approached by someone about it, therefore it's that time again where you need to file an Issue. The idea is the following:

Add anoptional way of decorating a callback handler with its routing definitions. All ourCommandHandlers,MessageHandlers etc. would get their corresponding decorators that can be used on top of callbacks, i.e. like this:

from mybot.dispatcher import command_handler, message_handler, callback_handler@message_handler(Filters.group & Filters.reply)def reply_in_group(bot, update):    pass@command_handler("start")@command_handler("help")def help(bot, update):    # Multiple handlers for a callback    update.message.reply_text("Help message")@callback_handler(pattern='my-cb')def button_callback(bot, update):    pass

This was the tl;dr part, for some deeper examination, read on.

Current state

Now traditionally, we've had all our handlers+callback setup in a routing block which is, for most users anyway, located near the instantiation of updater and dispatcher. Some might have gone so far as to put all thedispatcher.add_handler calls inside its own file (e.g.routing.py), providing a convenient top-down/outside-in access to all the handlers. The workflow with this is something likeneed to change the name of a command or add some synonyms? No problem, know where to look, it's all right there...

What I usually do is to have logically relatedcomponents that are actually reusable, but this only makes sense on larger scale and is not efficient for smaller bots.

In this philosophy, the routing happens outside of the handlers, in that they're decoupled from the place where they're used. I'm not sure if this was a concious design decision, or a construct that established over time...@jh0ker?
However,@Eldinnie made me aware that we are already breaking this convention by defining flow actions inside callbacks with the return values ofConversationHandlers, which is another reason I'm not holding back anymore with this enhancement proposal.

So far, so good. This philosophy works great, especially for larger projects, so I wouldn't wanna drop or change it.

With decorators

The second option allows for a setup where you can tell from a single glance at a callback signature how it is used and which bot functionalities are affected by this particular handler, increasing readability for you and discoverability for others reading your code, as well as code locality.

This also fixes the reusability of individual handlers in small bot environments. Say you have a command/developer (dev info) that you want to reuse in a couple of projects, then it will be cumbersome and inefficient to copy-paste the handler, and also search for its correspondingdispatcher.add_handler line. With a decorator, everything is in the same spot: Easy to give advice in the Telegram group or update our snippets with routing examples that don't feel out of place.

A point to consider is that is that by coupling the routing logic with a handler, you'd actually be decoupling the dispatcher object away from a "single point of use", forcing its distribution across all of your handler modules, making all these modules dependent on a dispatcher object. In thecomponents modularization I described above, it makes sense to have a methodregister(dispatcher) within the module that takes a dispatcher as argument and preserves the traditional direction of dependencies. With routing, you need to actuallyimport the dispatcher (which might, or might not be a good idea, again depending on project size).

I would like to offerboth options to our users. I don't see a reason why not to, but please come forward if you see problems with this method other that the ones I mentioned, and let me know what you think about it overall.

I'm aware that@tsnoam, one of the core devs who will genuinely hate me for bringing up this idea, is categorically against decorators, but I know a lot of people that like and see value in them. It is common practice in many other bot and web frameworks, particularly the folks atpyTelegramBotAPI who use this method to their advantage, providing a lot of utility and readability.

We're also gonna have to think about border cases like the conversation handler, perhaps we can come up with a nice solution for it.

This would also be a good opportunity to rethink#859, because all thepass_* denotations are going to be cumbersome, make the line very long, and add no value in terms of readability since the associated part where they're actually required is just one line below in the method signature (and not miles away in the routing block). Perhaps a hybrid approach would be suitable, where only the "already inherently magical" decorators are capable of autowiring, but not the traditional handler classes...