telegram.ext.Dispatcher

class telegram.ext.Dispatcher(bot: Bot, update_queue: queue.Queue, workers: int = 4, exception_event: threading.Event = None, job_queue: JobQueue = None, persistence: telegram.ext.basepersistence.BasePersistence = None, use_context: bool = True)

Bases: object

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.
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
add_error_handler(callback: Callable[[object, telegram.ext.callbackcontext.CallbackContext], None], run_async: Union[bool, telegram.utils.helpers.DefaultValue] = False) → None

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: telegram.ext.handler.Handler, group: int = 0) → None

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: Optional[object], error: Exception, promise: telegram.ext.utils.promise.Promise = None) → 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 = None

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() → telegram.ext.dispatcher.Dispatcher

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: object) → None

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: Callable[[object, telegram.ext.callbackcontext.CallbackContext], None]) → None

Removes an error handler.

Parameters:callback (callable) – The error handler to remove.
remove_handler(handler: telegram.ext.handler.Handler, group: int = 0) → None

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: Callable[[...], object], *args, update: object = None, **kwargs) → telegram.ext.utils.promise.Promise

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 = None

Indicates if this dispatcher is running.

Type:bool
start(ready: threading.Event = None) → 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() → None

Stops the thread.

update_persistence(update: object = None) → 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) –