René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Add decorators for routing definitions","articleBody":"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:\r\n\r\nAdd an **optional** way of decorating a callback handler with its routing definitions. All our `CommandHandlers`, `MessageHandlers` etc. would get their corresponding decorators that can be used on top of callbacks, i.e. like this:\r\n```\r\nfrom mybot.dispatcher import command_handler, message_handler, callback_handler\r\n\r\n\r\n@message_handler(Filters.group \u0026 Filters.reply)\r\ndef reply_in_group(bot, update):\r\n    pass\r\n\r\n\r\n@command_handler(\"start\")\r\n@command_handler(\"help\")\r\ndef help(bot, update):\r\n    # Multiple handlers for a callback\r\n    update.message.reply_text(\"Help message\")\r\n\r\n\r\n@callback_handler(pattern='my-cb')\r\ndef button_callback(bot, update):\r\n    pass\r\n```\r\n\r\nThis was the tl;dr part, for some deeper examination, read on.\r\n\r\n#### Current state\r\nNow 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 the `dispatcher.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 like _need to change the name of a command or add some synonyms? No problem, know where to look, it's all right there..._\r\n\r\nWhat I usually do is to have logically related _components_ that are actually reusable, but this only makes sense on larger scale and is not efficient for smaller bots.\r\n\r\n\u003e 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?\r\nHowever, @Eldinnie made me aware that we are already breaking this convention by defining flow actions inside callbacks with the return values of `ConversationHandlers`, which is another reason I'm not holding back anymore with this enhancement proposal.\r\n\r\nSo far, so good. This philosophy works great, especially for larger projects, so I wouldn't wanna drop or change it.\r\n\r\n#### With decorators\r\nThe 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.\r\n\r\nThis 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 corresponding `dispatcher.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.\r\n\r\nA 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 the _components_ modularization I described above, it makes sense to have a method `register(dispatcher)` within the module that takes a dispatcher as argument and preserves the traditional direction of dependencies. With routing, you need to actually *import* the dispatcher (which might, or might  not be a good idea, again depending on project size).\r\n\r\nI would like to offer *both* 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.\r\n\r\nI'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 at [pyTelegramBotAPI](https://github.com/eternnoir/pyTelegramBotAPI#message-handlers) who use this method to their advantage, providing a lot of utility and readability.\r\n\r\nWe're also gonna have to think about border cases like the conversation handler, perhaps we can come up with a nice solution for it.\r\n\r\nThis would also be a good opportunity to rethink #859, because all the `pass_*` 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...","author":{"url":"https://github.com/JosXa","@type":"Person","name":"JosXa"},"datePublished":"2017-11-02T02:21:57.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":10},"url":"https://github.com/899/python-telegram-bot/issues/899"}