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.
-
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 andrun_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
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 andrun_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 toTrue
uses the context based callback API (ignored if dispatcher argument is used). Defaults toTrue
. New users: set this toTrue
.
-
add_error_handler
(callback: Callable[[Any, telegram.ext.callbackcontext.CallbackContext], None], run_async: bool = 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: Update, context: CallbackContext)
The error that happened will be present in context.error.
- run_async (
bool
, optional) – Whether this handlers callback should be run asynchronously usingrun_async()
. Defaults toFalse
.
Note
See https://git.io/fxJuV for more info about switching to context based API.
- callback (
-
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. 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: Union[str, Update, None], error: Exception, promise: telegram.utils.promise.Promise = None) → None¶ Dispatches an error.
Parameters: - update (
str
|telegram.Update
| None) – 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.
- update (
-
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: Union[str, telegram.update.Update, telegram.error.TelegramError]) → None¶ Processes a single update.
Parameters: update ( str
|telegram.Update
|telegram.TelegramError
) – The update to process.
-
remove_error_handler
(callback: Callable[[Any, 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.
- handler (
-
run_async
(func: Callable[[...], Any], *args, update: Union[str, Update] = None, **kwargs) → telegram.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 totelegram.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 tofunc
. - update (
telegram.Update
, optional) – The update associated with the functions call. If passed, it will be available in the error handlers, in case an exception is raised byfunc
. - **kwargs (
dict
, optional) – Keyword arguments tofunc
.
Returns: Promise
- If you’re using
-
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: Union[str, Update] = None) → None¶ Update
user_data
,chat_data
andbot_data
inpersistence
.Parameters: - update (
telegram.Update
, optional) – The update to process. If passed, only the - user_data and chat_data will be updated. (corresponding) –
- update (
-