telegram.ext.Dispatcher

class telegram.ext.Dispatcher(bot, update_queue, workers=4, exception_event=None, job_queue=None, persistence=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.

user_data

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

chat_data

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

persistence

telegram.ext.BasePersistence – Optional. The persistence class to store data that should be persistent over restarts

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.
  • persistence (telegram.ext.BasePersistence, optional) – The persistence class to store data that should be persistent over restarts
add_error_handler(callback)

Registers an error handler in the Dispatcher.

Parameters:callback (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. If telegram.ext.DispatcherHandlerStop is raised from one of the handlers, no further handlers (regardless of the group) will be called.

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 (see telegram.ext.Handler.check_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.
dispatch_error(update, error)

Dispatches an error.

Parameters:
  • update (str | telegram.Update | None) – 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 | telegram.TelegramError) – The update to process.
remove_error_handler(callback)

Removes an error handler.

Parameters:callback (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(ready=None)

Thread target of thread ‘dispatcher’.

Runs in background and processes the update queue.

Parameters:ready (threading.Event, optional) – If specified, the event will be set once the dispatcher is ready.
stop()

Stops the thread.