telegram.ext.Dispatcher

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

Bases: object

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

bot

The bot object that should be passed to the handlers.

Type:telegram.Bot
update_queue

The synchronized queue that will contain the updates.

Type:Queue
job_queue

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

Type:telegram.ext.JobQueue
workers

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

Type:int
user_data

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

Type:defaultdict
chat_data

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

Type:defaultdict
bot_data

A dictionary handlers can use to store data for the bot.

Type:dict
persistence

Optional. The persistence class to store data that should be persistent over restarts

Type:telegram.ext.BasePersistence
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
  • use_context (bool, optional) – If set to True Use the context based callback API. During the deprecation period of the old API the default is False. New users: set this to True.
add_error_handler(callback)

Registers an error handler in the Dispatcher. This handler will receive every error which happens in your bot.

Warning: The errors handled within these handlers won’t show up in the logger, so you need to make sure that you reraise the error.

Parameters:callback (callable) –

The callback function for this error handler. Will be called when an error is raised. Callback signature for context based API:

def callback(update: Update, context: CallbackContext)

The error that happened will be present in context.error.

Note

See https://git.io/fxJuV for more info about switching to context based API.

add_handler(handler, group=0)

Register a handler.

TL;DR: Order and priority counts. 0 or 1 handlers per group will be used. End handling of update with telegram.ext.DispatcherHandlerStop.

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 (Exception) – The error that was raised.
error_handlers = None

A list of errorHandlers.

Type:List[callable]
classmethod get_instance()

Get the singleton instance of this class.

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

A list with all groups.

Type:List[int]
handlers = None

Holds the handlers per group.

Type:Dict[int, List[telegram.ext.Handler]]
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.

Warning

If you’re using @run_async you cannot rely on adding custom attributes to telegram.ext.CallbackContext. See its docs for more info.

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

Indicates if this dispatcher is running.

Type:bool
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.

update_persistence(update=None)

Update user_data, chat_data and bot_data in persistence.

Parameters:
  • update (telegram.Update, optional) – The update to process. If passed, only the
  • user_data and chat_data will be updated. (corresponding) –