telegram.ext.CallbackContext¶
-
class
telegram.ext.
CallbackContext
(dispatcher)¶ This is a context object passed to the callback called by
telegram.ext.Handler
or by thetelegram.ext.Dispatcher
in an error handler added bytelegram.ext.Dispatcher.add_error_handler
or to the callback of atelegram.ext.Job
.Note
telegram.ext.Dispatcher
will create a single context for an entire update. This means that if you got 2 handlers in different groups and they both get called, they will get passed the same CallbackContext object (of course with proper attributes like .matches differing). This allows you to add custom attributes in a lower handler group callback, and then subsequently access those attributes in a higher handler group callback. Note that the attributes on CallbackContext might change in the future, so make sure to use a fairly unique name for the attributes.Warning
Do not combine custom attributes and
@run_async
/telegram.ext.Disptacher.run_async()
. Due to howrun_async
works, it will almost certainly execute the callbacks for an update out of order, and the attributes that you think you added will not be present.- Parameters
dispatcher (
telegram.ext.Dispatcher
) – The dispatcher associated with this context.
-
matches
¶ Optional. If the associated update originated from a regex-supported handler or had a
Filters.regex
, this will contain a list of match objects for every pattern wherere.search(pattern, string)
returned a match. Note that filters short circuit, so combined regex filters will not always be evaluated.- Type
List[
re match object
]
-
args
¶ Optional. Arguments passed to a command if the associated update is handled by
telegram.ext.CommandHandler
,telegram.ext.PrefixHandler
ortelegram.ext.StringCommandHandler
. It contains a list of the words in the text after the command, using any whitespace string as a delimiter.- Type
List[
str
]
-
error
¶ Optional. The error that was raised. Only present when passed to a error handler registered with
telegram.ext.Dispatcher.add_error_handler
.- Type
Exception
-
async_args
¶ Optional. Positional arguments of the function that raised the error. Only present when the raising function was run asynchronously using
telegram.ext.Dispatcher.run_async()
.- Type
List[
object
]
-
async_kwargs
¶ Optional. Keyword arguments of the function that raised the error. Only present when the raising function was run asynchronously using
telegram.ext.Dispatcher.run_async()
.- Type
Dict[
str
,object
]
-
job
¶ Optional. The job which originated this callback. Only present when passed to the callback of
telegram.ext.Job
.- Type
-
property
bot
¶ The bot associated with this context.
- Type
-
property
bot_data
¶ Optional. A dict that can be used to keep any data in. For each update it will be the same
dict
.- Type
dict
-
property
chat_data
¶ Optional. A dict that can be used to keep any data in. For each update from the same chat id it will be the same
dict
.Warning
When a group chat migrates to a supergroup, its chat id will change and the
chat_data
needs to be transferred. For details see our wiki page.- Type
dict
-
property
dispatcher
¶ The dispatcher associated with this context.
-
drop_callback_data
(callback_query)¶ Deletes the cached data for the specified callback query.
New in version 13.6.
Note
Will not raise exceptions in case the data is not found in the cache. Will raise
KeyError
in case the callback query can not be found in the cache.- Parameters
callback_query (
telegram.CallbackQuery
) – The callback query.- Raises
KeyError | RuntimeError –
KeyError
, if the callback query can not be found in the cache andRuntimeError
, if the bot doesn’t allow for arbitrary callback data.
-
classmethod
from_error
(update, error, dispatcher, async_args=None, async_kwargs=None)¶ Constructs an instance of
telegram.ext.CallbackContext
to be passed to the error handlers.- Parameters
update (
object
|telegram.Update
) – The update associated with the error. May beNone
, e.g. for errors in job callbacks.error (
Exception
) – The error.dispatcher (
telegram.ext.Dispatcher
) – The dispatcher associated with this context.async_args (List[
object
]) – Optional. Positional arguments of the function that raised the error. Pass only when the raising function was run asynchronously usingtelegram.ext.Dispatcher.run_async()
.async_kwargs (Dict[
str
,object
]) – Optional. Keyword arguments of the function that raised the error. Pass only when the raising function was run asynchronously usingtelegram.ext.Dispatcher.run_async()
.
- Returns
-
classmethod
from_job
(job, dispatcher)¶ Constructs an instance of
telegram.ext.CallbackContext
to be passed to a job callback.See also
- Parameters
job (
telegram.ext.Job
) – The job.dispatcher (
telegram.ext.Dispatcher
) – The dispatcher associated with this context.
- Returns
-
classmethod
from_update
(update, dispatcher)¶ Constructs an instance of
telegram.ext.CallbackContext
to be passed to the handlers.- Parameters
update (
object
|telegram.Update
) – The update.dispatcher (
telegram.ext.Dispatcher
) – The dispatcher associated with this context.
- Returns
-
property
job_queue
¶ The
JobQueue
used by thetelegram.ext.Dispatcher
and (usually) thetelegram.ext.Updater
associated with this context.
-
property
match
¶ The first match from
matches
. Useful if you are only filtering using a single regex filter. Returns None ifmatches
is empty.- Type
Regex match type
-
refresh_data
()¶ If
dispatcher
uses persistence, callstelegram.ext.BasePersistence.refresh_bot_data()
onbot_data
,telegram.ext.BasePersistence.refresh_chat_data()
onchat_data
andtelegram.ext.BasePersistence.refresh_user_data()
onuser_data
, if appropriate.New in version 13.6.
-
update
(data)¶ Updates
self.__slots__
with the passed data.- Parameters
data (Dict[
str
,object
]) – The data.
-
property
update_queue
¶ The
Queue
instance used by thetelegram.ext.Dispatcher
and (usually) thetelegram.ext.Updater
associated with this context.- Type
queue.Queue
-
property
user_data
¶ Optional. A dict that can be used to keep any data in. For each update from the same user it will be the same
dict
.- Type
dict