Support for `Annotated` dependencies

[chrisguidry]

We're using dependencies to control most of the behavior of Docket, and the current kwarg-default style is the most useful for when you need to interact with the dependency itself:

async def high_five_customer(
    customer: int,
    db: Connection = Depends(get_connection),
):
   customer = db.query(...., customer)
   ...

But there are times when a dependency needs to refer to a parameter, like with concurrency limiting:

async def high_five_customer(
    customer: Annotated[int, ConcurrencyLimit(1)),
    db: Connection = Depends(get_connection),
):
   customer = db.query(...., customer)
   ...

This makes sure we don't look unhinged and try to high five our customers too many times at once :D (see #163).

Still further, we are hopping through some quirky type hoops to connect the type of the defaults to the type of the parameter, and Annotated gives us a cleaner way out of that as well:

async def high_five_customer(
    customer: int,
    db: Annotated[Connection, Depends(get_connection)],
):
   customer = db.query(...., customer)
   high_five(customer)

This also lets you define reusable dependencies with a little less work:

Connection = Annotated[PostgresConnection, Depends(get_connection)]

async def high_five_customer(customer: int, db: Connection):
   customer = db.query(...., customer)
   high_five(customer)

This has the benefit of allowing us to specify multiple dependencies that relate to a parameter:

async def high_five_customer(
    customer: Annotated[int, ConcurrencyLimit(1)], 
    db: Annotated[Connection, Depends(get_connection), ConcurrencyLimit(4)]
):
   customer = db.query(...., customer)
   high_five(customer)

This would express, for example, that we support 4 db connections at a time but only 1 customer at a time, for example.

[DanCardin]

I dont know if you need this, because you already have signature traversal and type hint related code (at least in fastmcp, i didn't keep track of what was in the vendored docket vs not); but I have my own package which implements a very similar fastapi-like depends system (which only works through types). And https://github.com/litestar-org/type-lens was a big part of what made it sane to handle the sharper edge cases of python's type introspection capabilities. For whatever that may be worth.

[omikader]

Looked into this — there's a type-checking issue with Annotated that's worth discussing.

docket.add() preserves the task's full signature via ParamSpec:

def add(self, function: Callable[P, Awaitable[R]], ...) -> Callable[P, Awaitable[Execution]]:

With default-value style, Depends() returns cast(R, ...) so pyright sees a default value and treats the parameter as optional:

async def my_task(db: Connection = Depends(get_connection)): ...
await docket.add(my_task)()  # ✅ pyright sees db as optional

With Annotated, pyright sees a required parameter with no default:

async def my_task(db: Annotated[Connection, Depends(get_connection)]): ...
await docket.add(my_task)()  # ❌ pyright: missing required argument "db"

FastAPI doesn't hit this because users never call route handlers directly — the framework does. In docket, users call through add() which forwards the full ParamSpec, so every Annotated dependency becomes a false type error at the call site.

To my knowledge, Python's type system doesn't support filtering or transforming a ParamSpec, so there's no clean way for add() to strip injected params from the return type. Some options:

1. Pyright/mypy plugin — could teach the type checker that Annotated[T, Depends(...)] params are framework-injected. Full type safety, but a significant standalone effort.
2. Loosen the return type — add() returns Callable[..., Awaitable[Execution]] instead of Callable[P, ...]. No false errors, but loses all argument type checking for every task.
3. Don't support Annotated — the default-value style already works cleanly with type checkers.

[DanCardin]

Perhaps an alternative api to add which returns a less strictly typed result like option 2 but which otherwise does the same thing? If you're a direct consumer of docket, this is probably a more relevant concern. But in the motivating case, FastMCP itself a framework using docket as a dependency resolver, so it's going to be programmatically calling the underlying handlers such that I would assume the signature information isn't important at that level anyway.

[chrisguidry]

Great convo, folks, thank you! @omikader you've changed my mind about this, specifically because of your PR showing that you had to use # pyright: ignore[reportCallIssue], that's pointing out exactly the problem.

What do you think about dialing this back to be more of strictly annotation on existing parameters, but not ones that can provide a value. So like ConcurrencyLimit is the perfect example:

async def high_five_customer(
    customer: Annotated[int, ConcurrencyLimit(1)], 
    db: Annotated[Connection, Depends(get_connection), ConcurrencyLimit(4)]
):

So it would be available for any case where you don't need to interact with the return value, but like the ConcurrencyLimit dependency itself gets a reference to the field name it was applied to, but otherwise the return value isn't used. This would be similar to how things like the Logged annotation works. It would still get the __aenter__/__aexit__ calls around the task.

What do you think of that approach? I'm not sure if it even changes too much about your PR, just maybe the example?

[chrisguidry]

@DanCardin thanks for the pointer to your library, will take a look! I do have a goal of splitting Docket's dependency system into a separate library one day.