Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# BaseHandler

class telegram.ext.BaseHandler(callback, block=True)

  Bases: `typing.Generic`, `ABC`

  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.

  Available In

  `telegram.ext.Application.handlers`

  See also

  Types of Handlers

  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

    The callback function for this handler.

    Type:

      coroutine function

  block

    Determines whether the callback will run in a blocking way.

    Type:

      `bool`

  __repr__()

    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`

  abstract check_update(update)

    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)

    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)

    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.