telegram.ext.Dispatcher

class telegram.ext.Dispatcher(bot, update_queue, workers=4, exception_event=None, job_queue=None)

Bases: object

This class dispatches all kinds of updates to its registered handlers.

bot

telegram.Bot – The bot object that should be passed to the handlers.

update_queue

Queue – The synchronized queue that will contain the updates.

job_queue

telegram.ext.JobQueue – Optional. The telegram.ext.JobQueue instance to pass onto handler callbacks.

workers

int – Number of maximum concurrent worker threads for the @run_async decorator.

Parameters:
  • bot (telegram.Bot) – The bot object that should be passed to the handlers.
  • update_queue (Queue) – The synchronized queue that will contain the updates.
  • job_queue (telegram.ext.JobQueue, optional) – The telegram.ext.JobQueue instance to pass onto handler callbacks.
  • workers (int, optional) – Number of maximum concurrent worker threads for the @run_async decorator. defaults to 4.
add_error_handler(callback)

Registers an error handler in the Dispatcher.

Parameters:handler (callable) – A function that takes Bot, Update, TelegramError as arguments.
add_handler(handler, group=0)

Register a handler.

TL;DR: Order and priority counts. 0 or 1 handlers per group will be used.

A handler must be an instance of a subclass of telegram.ext.Handler. All handlers are organized in groups with a numeric value. The default group is 0. All groups will be evaluated for handling an update, but only 0 or 1 handler per group will be used.

The priority/order of handlers is determined as follows:

  • Priority of the group (lower group number == higher priority)
  • The first handler in a group which should handle an update will be used. Other handlers from the group will not be used. The order in which handlers were added to the group defines the priority.
Parameters:
  • handler (telegram.ext.Handler) – A Handler instance.
  • group (int, optional) – The group identifier. Default is 0.
chat_data = None

dict – A dictionary handlers can use to store data for the chat.

dispatch_error(update, error)

Dispatches an error.

Parameters:
  • update (str | telegram.Update) – The update that caused the error
  • error (telegram.TelegramError) – The Telegram error that was raised.
error_handlers = None

List[callable] – A list of errorHandlers.

classmethod get_instance()

Get the singleton instance of this class.

Returns:telegram.ext.Dispatcher
Raises:RuntimeError
groups = None

List[int] – A list with all groups.

handlers = None

Dict[int, List[telegram.ext.Handler]] – Holds the handlers per group.

process_update(update)

Processes a single update.

Parameters:update (str | telegram.Update) – The update to process.
remove_error_handler(callback)

Removes an error handler.

Parameters:handler (callable) – The error handler to remove.
remove_handler(handler, group=0)

Remove a handler from the specified group

Parameters:
  • handler (telegram.ext.Handler) – A Handler instance.
  • group (object, optional) – The group identifier. Default is 0.
run_async(func, *args, **kwargs)

Queue a function (with given args/kwargs) to be run asynchronously.

Parameters:
  • func (callable) – The function to run in the thread.
  • *args (tuple, optional) – Arguments to func.
  • **kwargs (dict, optional) – Keyword arguments to func.
Returns:

Promise

running = None

bool – Indicates if this dispatcher is running.

start()

Thread target of thread ‘dispatcher’. Runs in background and processes the update queue.

stop()

Stops the thread.

user_data = None

dict – A dictionary handlers can use to store data for the user.