This issue is here to expose to the community a proposed design for the Handlers callback prototype.
We have recently closed/rejected PR #859 in this subject as we preferred to go in a different direction. Here we intend to discuss with the community what will be the chosen design.

Current situation:
Minimal callback prototype is def callback(bot, update).
If users require more data/facilities they can initialize the Handler with extra pass_ (bool) arguments which mandates the callback to accept more arguments (like groups, args and others).

Problems:

• The API is very cumbersome and confusing for new users.
• Adding/pushing new context data into the callbacks requires code changes from the users.
  Lets say that we want the RegexHandler to provide the match object to the callback. With the current design it will be impossible to add that information without changing the callback prototype and (most likely) impose a new pass_ parameter during Handler initialization.

Proposed API
IMPORTANT: This change is non backward compatible. We might implement a backward compatibility layer for a certain period like we have done with other deprecated mechanisms in the past.

• Deprecate pass_ arguments when initializing Handlers.
• Handler callbacks prototype will change to: def callback(update, ctx).
• The above ctx will be a context of all information/facilities that users may need. The context will be a Mixin of various context objects, depending on the Handler.
  Examples of such information/facilities:
  • bot
  • update_queue
  • job_queue (something to think about: instead of updater_queue & job_queue, pass the updater)
  • user_data
  • chat_data
  • match (instead of groups, groups_dict and similar for).