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
-
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) – Thetelegram.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 toTrue
Use the context based callback API. During the deprecation period of the old API the default isFalse
. New users: set this toTrue
.
-
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.
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. Iftelegram.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.
- update (
-
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.
- handler (
-
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
- func (
-
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
andchat_data
inpersistence
.
-
user_data
= None A dictionary handlers can use to store data for the user.
Type: dict
-