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 user_data, chat_data and bot_data in persistence.