BaseHandler¶

class telegram.ext.BaseHandler(callback, block=True)[source]¶

Bases: ABC, typing.Generic

The base class for all update handlers. Create custom handlers by inheriting from it.

Warning

When setting block to False, you cannot rely on adding custom attributes to telegram.ext.CallbackContext. See its docs for more info.

This class is a Generic class and accepts three type variables:

1. The type of the updates that this handler will handle. Must coincide with the type of the first argument of callback. check_update() must only accept updates of this type.

2. The type of the second argument of callback. Must coincide with the type of the parameters handle_update.context and collect_additional_context.context as well as the second argument of callback. Must be either CallbackContext or a subclass of that class.

   Tip

   For this type variable, one should usually provide a TypeVar that is also used for the mentioned method arguments. That way, a type checker can check whether this handler fits the definition of the Application.

3. The return type of the callback function accepted by this handler.

See also

Types of Handlers

Use In

• telegram.ext.Application.add_handler()

• telegram.ext.Application.add_handlers()

• telegram.ext.Application.remove_handler()

Available In

• telegram.ext.ConversationHandler.entry_points

• telegram.ext.ConversationHandler.fallbacks

• telegram.ext.ConversationHandler.states

Changed in version 20.0:

• The attribute run_async is now block.

• This class was previously named Handler.

Parameters:

• callback (coroutine function) –

  The callback function for this handler. Will be called when check_update() has determined that an update should be processed by this handler. Callback signature:

  async def callback(update: Update, context: CallbackContext)
  

  The return value of the callback is usually ignored except for the special case of telegram.ext.ConversationHandler.

• block (bool, optional) –

  Determines whether the return value of the callback should be awaited before processing the next handler in telegram.ext.Application.process_update(). Defaults to True.

  See also

  Concurrency

callback[source]¶

The callback function for this handler.

Type:

coroutine function

block[source]¶

Determines whether the callback will run in a blocking way.

Type:

bool

__repr__()[source]¶

Give a string representation of the handler in the form ClassName[callback=...].

As this class doesn’t implement object.__str__(), the default implementation will be used, which is equivalent to __repr__().

Returns:

str

abstractmethod check_update(update)[source]¶

This method is called to determine if an update should be handled by this handler instance. It should always be overridden.

Note

Custom updates types can be handled by the application. Therefore, an implementation of this method should always check the type of update.

Parameters:

update (object | telegram.Update) – The update to be tested.

Returns:

Either None or False if the update should not be handled. Otherwise an object that will be passed to handle_update() and collect_additional_context() when the update gets handled.

collect_additional_context(context, update, application, check_result)[source]¶

Prepares additional arguments for the context. Override if needed.

Parameters:

• context (telegram.ext.CallbackContext) – The context object.

• update (telegram.Update) – The update to gather chat/user id from.

• application (telegram.ext.Application) – The calling application.

• check_result – The result (return value) from check_update().

async handle_update(update, application, check_result, context)[source]¶

This method is called if it was determined that an update should indeed be handled by this instance. Calls callback along with its respectful arguments. To work with the telegram.ext.ConversationHandler, this method returns the value returned from callback. Note that it can be overridden if needed by the subclassing handler.

Parameters:

• update (str | telegram.Update) – The update to be handled.

• application (telegram.ext.Application) – The calling application.

• check_result (object) – The result from check_update().

• context (telegram.ext.CallbackContext) – The context as provided by the application.