Improving Type Safety of Annotated Dependencies: (implemented: a run-time approach, TODO: compile-time)

[jsimonlane]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the FastAPI documentation, with the integrated search.
• I already searched in Google "How to X in FastAPI" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to FastAPI but to Pydantic.
• I already checked if it is not related to FastAPI but to Swagger UI.
• I already checked if it is not related to FastAPI but to ReDoc.

Commit to Help

• I commit to help with one of those options 👆

Example Code

######## VERSION 1 ########
# This works fine -- it sets the stage

from fastapi import FastAPI, Depends

class OriginalDB():
    def log_visit(self) -> None:
        pass

def get_db() -> OriginalDB:
    return OriginalDB()

DBDep = t.Annotated[OriginalDB, Depends(get_db)]

app = FastAPI()

@app.get("/")
def read_root(db: DBDep) -> str:
    db.log_visit()
    return "great!"

But then, imagine a case where we upgrade our DB (and its dependency), but forget to annotate the dependency accordingly.

######## Version 2 ########
# The problem here is, our 'annotation' function below lies to us!
from fastapi import FastAPI, Depends

class OriginalDB():
    def log_visit(self) -> None:
        pass

class NewDB():
    def better_log_visit(self, priority: int) -> None:
        "Improved because maybe we geo-weight some regions"
        pass

def get_better_db() -> NewDB:
    return NewDB()

DBDep = t.Annotated[OriginalDB, Depends(get_better_db)] # <------------- BUG!

@app.get("/")
def read_root(db: DBDep) -> str:
    # ERROR! Should be `better_log_visit`, but mypy doesn't catch it.
    # Ideally we'd catch this at compile time, but we don't until the route is called.
    db.log_visit()
    return "great!"

The above would crash at runtime, and our compiler would not help us.

To fix this, we can use this function I made:

######## Prelim Solution ########
def validate_annotation(
    annotation: t.Annotated[t.Any, ...],
    dependency_function: t.Callable[..., t.Any]
) -> None:
    """
    Assert that the dependency function outputs a correctly annotated type.
    """
    annotation_type = t.get_args(annotation)[0]
    return_type = t.get_type_hints(dependency_function)["return"]
    if annotation_type != return_type:
        raise ValueError(f"Annotation validation failed: {annotation_type} != {return_type}")
    assert(annotation_type == return_type)

DBDep = t.Annotated[OriginalDB, Depends(get_better_db)]
validate_annotation(DBDep, get_better_db) # THIS THROWS
# Would not throw if "DBDep" were annotated with the "NewDB"
# validate_annotation(NewDB, get_better_db)

Description

The core problem is duplication of information -- when you define dependencies, that t.Annotated[] bit isn't based off the truth, but rather a value you expect it to be.

This leads to issues found at runtime and bespoke checks -- for instance, this recent issue uses 'assert' in the body to double check the correctness of the dependency.

We want to do this at compile time.

Unfortunately, I couldn't find a way to get the Python Type checker to dynamically generate the right dependency... it was tricky.

However, my above approach does it when the server boots, which is the next best thing. Fixing this check makes the annotation updated correctly, and the typing to work from there.

Operating System

macOS

Operating System Details

No response

FastAPI Version

0.109.1

Pydantic Version

1.10.14

Python Version

Python 3.11.6

Additional Context

No response

[YuriiMotov]

This PR 11255 allows you to find such errors using type checkers