How to correctly pass dependencies to handler? #4902

nectarindev · 2025-08-07T22:06:13Z

nectarindev
Aug 7, 2025

I recently tried to implement code with something like the following structure:

from telegram.ext import ApplicationBuilder, CommandHandler, ContextTypes
from telegram import Update


class MyService: ...


async def hello(update: Update, context: ContextTypes.DEFAULT_TYPE):
    # somehow get the service and do something useful
    service: MyService = ...
    ...


def main():
    # сreate instances of the required classes
    service = MyService(...)

    app = ApplicationBuilder().token("...").build()
    app.add_handler(CommandHandler("hello", hello))

    # somehow bind the service to the application 
    # so that it can be retrieved later in the handler.
    ...

    app.run_polling()

I'd be surprised there isn't a recommended way to do this easily, or I didn't read the documentation well.

I understand that we can write something like this:

# in main
app.service = service # just create attribute dynamically

# in handler
service = typing.cast(MyService, context.application.service)

or like this

# in main
app.bot_data["service"] = service

# in handler
service = typing.cast(MyService, context.bot_data["service"])

or even make a variable at the module level.

But these solutions look dirty from the point of view of typing and testability.

The closest result I was able to achieve was using custom Application and CallbackContext classes.

Full code example

import typing as t

from telegram import Update
from telegram.ext import (
    ApplicationBuilder,
    Application,
    CommandHandler,
    ContextTypes,
    CallbackContext,
    ExtBot,
)


ADict = dict[t.Any, t.Any]


class MyService: ...


class MyApplication(Application):
    def __init__(self, service: MyService, **kwargs):
        super().__init__(**kwargs)
        self.service = service


class MyContext(CallbackContext[ExtBot[None], ADict, ADict, ADict]):
    @property
    def service(self):
        return t.cast(MyApplication, self.application).service


async def hello(update: Update, context: MyContext) -> None:
    print(context.service) # <__main__.MyService object at 0x7f174d334680>


def main():
    service = MyService()

    context_types = ContextTypes(context=MyContext)

    app = (
        ApplicationBuilder()
        .application_class(MyApplication, {"service": service})
        .context_types(context_types)
        .token("...")
        .build()
    )
    app.add_handler(CommandHandler("hello", hello))
    app.run_polling()

But even here we need to use type cast because in the context the application property is annotated as Application[ExtBot[None], Any, ADict, ADict, ADict, Any], despite the fact that in ApplicationBuilder we specified our application class.

In general, I would like to know if my last example can be made better, maybe there are other alternatives and I missed something?
It is also strange that I did not find issues and discussions on a similar topic, although the topic, in my opinion, is important. It is very interesting how others played with such a problem.

Answered by Poolitzer

Aug 7, 2025

I usually use a custom context, see e.g. https://github.com/python-telegram-bot/ptbcontrib/tree/main/ptbcontrib/username_to_chat_api or https://docs.python-telegram-bot.org/en/stable/examples.contexttypesbot.html

Not sure that's fully accommodating of your fully type cast example here

View full answer

Poolitzer · 2025-08-07T22:13:57Z

Poolitzer
Aug 7, 2025
Collaborator

I usually use a custom context, see e.g. https://github.com/python-telegram-bot/ptbcontrib/tree/main/ptbcontrib/username_to_chat_api or https://docs.python-telegram-bot.org/en/stable/examples.contexttypesbot.html

Not sure that's fully accommodating of your fully type cast example here

0 replies

RoxyBasicNeedBot · 2025-12-13T04:47:21Z

RoxyBasicNeedBot
Dec 13, 2025

The Object-Oriented Approach (Recommended)
This is the most Pythonic solution. Instead of standalone functions, group your handlers into a class that accepts your dependencies (MyService) in its constructor.

This binds the service to the instance, making it available via self in your handlers. No globals, no bot_data, and perfect type safety.

Python

from telegram import Update
from telegram.ext import ApplicationBuilder, CommandHandler, ContextTypes

class MyService:
def do_work(self):
return "Service is working!"

class BotHandlers:
def init(self, service: MyService):
self.service = service

async def hello(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
    # Access service via self
    result = self.service.do_work()
    await update.message.reply_text(result)

def main():
service = MyService()
# Instantiate the handler class with dependencies
handlers = BotHandlers(service)

app = ApplicationBuilder().token("TOKEN").build()

# Register the bound method
app.add_handler(CommandHandler("hello", handlers.hello))

app.run_polling()

The functools.partial Approach
If you prefer keeping handlers as standalone functions but want to inject dependencies, you can use functools.partial. This "bakes" the service argument into the function before the library ever sees it.

Python

import functools
from telegram import Update
from telegram.ext import ApplicationBuilder, CommandHandler, ContextTypes

Define handler with an EXTRA argument for the service

async def hello(update: Update, context: ContextTypes.DEFAULT_TYPE, service: MyService):
await update.message.reply_text(f"Service says: {service.do_work()}")

def main():
service = MyService()

# Create a partial function with 'service' pre-filled
# The PTB library will still pass 'update' and 'context' as usual
handler_with_service = functools.partial(hello, service=service)

app = ApplicationBuilder().token("TOKEN").build()
app.add_handler(CommandHandler("hello", handler_with_service))
app.run_polling()

Analyzing Your Custom Context Solution
Your solution using MyApplication and MyContext is effectively the "Power User" way. It is the correct way to utilize PTB's generics if you want the framework to be aware of your types.

Why is the cast still necessary? You asked why t.cast is needed even though you passed MyApplication to the builder.

The issue lies in the definition of CallbackContext. In the PTB source code, the application property inside CallbackContext is typed as the base Application class (or a generic that defaults to it). Even though you injected MyApplication at runtime, the static type checker (mypy/pyright) cannot infer that this specific instance of Context is always linked to that specific subclass of Application without a circular generic dependency that is hard to express in Python.

Your property override is the correct fix:

Python

@Property
def service(self) -> MyService:
# This cast is the "bridge" between the generic framework
# and your concrete implementation. It is safe and encapsulated.
return t.cast(MyApplication, self.application).service

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

How to correctly pass dependencies to handler? #4902

Uh oh!

{{title}}

Uh oh!

Replies: 2 comments

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

How to correctly pass dependencies to handler? #4902

Uh oh!

nectarindev Aug 7, 2025

Replies: 2 comments

Uh oh!

Poolitzer Aug 7, 2025 Collaborator

Uh oh!

RoxyBasicNeedBot Dec 13, 2025

Define handler with an EXTRA argument for the service

nectarindev
Aug 7, 2025

Poolitzer
Aug 7, 2025
Collaborator

RoxyBasicNeedBot
Dec 13, 2025