telegram.ext.Dispatcher

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

Bases: Generic[telegram.ext.utils.types.CCT, telegram.ext.utils.types.UD, telegram.ext.utils.types.CD, telegram.ext.utils.types.BD]

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

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 and run_async(). 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 uses the context based callback API (ignored if dispatcher argument is used). Defaults to True. New users: set this to True.

  • context_types (telegram.ext.ContextTypes, optional) –

    Pass an instance of telegram.ext.ContextTypes to customize the types used in the context interface. If not passed, the defaults documented in telegram.ext.ContextTypes will be used.

    New in version 13.6.

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 and run_async().

Type

int, optional

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

context_types

Container for the types used in the context interface.

New in version 13.6.

Type

telegram.ext.ContextTypes

add_error_handler(callback, run_async=False)

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

Note

Attempts to add the same callback multiple times will be ignored.

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: object, context: CallbackContext)

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

  • run_async (bool, optional) – Whether this handlers callback should be run asynchronously using run_async(). Defaults to False.

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, promise=None)

Dispatches an error.

Parameters
  • update (object | telegram.Update) – The update that caused the error.

  • error (Exception) – The error that was raised.

  • promise (telegram.utils.Promise, optional) – The promise whose pooled function raised the error.

error_handlers: Dict[Callable, Union[bool, telegram.utils.helpers.DefaultValue]]

A dict, where the keys are error handlers and the values indicate whether they are to be run asynchronously.

Type

Dict[callable, bool]

classmethod get_instance()

Get the singleton instance of this class.

Returns

telegram.ext.Dispatcher

Raises

RuntimeError

groups: List[int]

A list with all groups.

Type

List[int]

handlers: Dict[int, List[telegram.ext.handler.Handler]]

Holds the handlers per group.

Type

Dict[int, List[telegram.ext.Handler]]

process_update(update)

Processes a single update and updates the persistence.

Note

If the update is handled by least one synchronously running handlers (i.e. run_async=False), update_persistence() is called once after all handlers synchronous handlers are done. Each asynchronously running handler will trigger update_persistence() on its own.

Parameters

update (telegram.Update | object | telegram.error.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, update=None, **kwargs)

Queue a function (with given args/kwargs) to be run asynchronously. Exceptions raised by the function will be handled by the error handlers registered with add_error_handler().

Warning

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

  • Calling a function through run_async() from within an error handler can lead to an infinite error handling loop.

Parameters
  • func (callable) – The function to run in the thread.

  • *args (tuple, optional) – Arguments to func.

  • update (telegram.Update | object, optional) – The update associated with the functions call. If passed, it will be available in the error handlers, in case an exception is raised by func.

  • **kwargs (dict, optional) – Keyword arguments to func.

Returns

Promise

running

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 corresponding user_data and chat_data will be updated.