Unclear how to create a background task with dependencies from within the handler scope

[scott2b]

This seems related to #666 but also more specific than that discussion.

Both Starlette and FastAPI have you define background tasks within the view and to pass it as the background parameter to the response object. This seems to be correctly scoped as it allows one to do background things with arbitrary resources that have been variously injected into, created within, or retrieved within the handling scope.

In Starlite, because the background function is referenced in the route decorator, it is not clear how one would pass in locally scoped resources as arguments to the background task.

The immediate solution that comes to mind is to return a Starlette JSONResponse and use the above mentioned pattern of specifying the background parameter in the response. However, I am currently having issues with rendering Starlette's JSONResponse and I think it may break the openapi docs if I do get it working (I'm not entirely sure about this latter point).

I am guessing that replacing Starlette responses will be the change that enables the pattern I am looking for here. Should I just wait for that, or is there a currently known approach for what I am trying to do with background tasks?

Thanks!

[provinzkraut]

This would be a documentation issue. You can add background tasks to your response as well, see the reference docs here.

So you can do something like

from starlite import Response, get, BackgroundTask


async def do_something_with_id(id: str) -> None:
    ...


@get("/with-background/{id:str}")
async def with_background(id: str) -> Response:
    return Response(
        content="",
        background=BackgroundTask(do_something_with_id, id=id),
    )

It's not advertised in the section about background tasks though, which it should be. I guess that's be something that should be covered in a tutorial section on background tasks, what do you think?

[scott2b]

Ah. Excellent. I am not sure why this did not occur to me, but makes perfect sense. Thank you so much.

Yes, I think placing the documentation for this in the section on background tasks would be ideal.

[scott2b]

As a follow-up, I am wondering if there is a way to get the openapi docs to display a specific response schema, and for that matter to get response validation to work. My thought was that I could pass the response_class to the route decorator, but that does not appear to affect anything.

I tried something like this:

from starlite import Response, get, BackgroundTask
from pydantic import BaseModel

class MyResponse(BaseModel):
    foo: str

@get("/testing", name="testing", response_class=MyResponse)
async def testing(request: Request) -> Response:
    ...
    return Response({ "foo": "justatest" }, background=BackgroundTask(sometask, someparam=something))

... thinking that the generic Response is required if I want to pass in a background task, but that the response_class parameter would take care of rendering the expected apidocs and do proper validation. Neither of those things seems to happen though.

[scott2b]

I realize now that my above example conflates the idea of a serializer with the idea of a response, so I tried this with a subclass with specified serializer instead:

class MySerializer(BaseModel):
    foo: str

class MyResponse(Response):

    @staticmethod
    def serializer(value: Any) -> Any:
        return MySerializer(value)

But I still don't get rendered documentation or validation.

[scott2b]

Ah. I got it! It's all very straightforward once you understand the pieces. I did something like this (no subclass required!)

async def do_something_with_user(user):
    print("Do something with the user.", user)


class FooSchema(BaseModel):
    foo: str


@get("/example")
async def example_with_background(request: Request) -> Response[FooSchema]:
    return Response(
        FooSchema(**{"foo": "bar"}),
        background=BackgroundTask(do_something_with_user, request.user)
    )

This should result both in proper OpenAPI documentation for the endpoint response as well as proper validation of the response.

[peterschutt]

Nice! Feel free to open an issue if you feel this can be documented better. @provinzkraut is putting together a project for an overhaul of the docs, so now is a good time for this type of feedback.

Cheers

[provinzkraut]

@scott2b Great that you figured it out, I'm sorry that the example I gave was incomplete! Would you mind telling me how the documentation could be clearer on this? Currently, this is covered in the section Returning Responses > Annotating Responses, what do you think would be a better place for this? Or more general: What would have helped you to easier find this?

[scott2b]

I'm not sure. I sort of got to the point of understanding through a series of trials and error. A couple of things may or may not be helpful, depending on peoples' doc-reading styles. For my part, I tend to read just enough documentation to get a picture of how things fit together conceptually, and then I refer back to the docs as I try to solve specific problems.

A conceptual overview of the moving parts might help.

There is some conceptual overlap among the parts of a defined route, and it is not always clear what part does what. I think this is particularly true of a response as a broad concept, which is effectively defined in at least 3 places:

1. The return type of the function
2. The actual thing returned from the function
3. The optional response_class parameter

Combined with the use of schemas and generics and the potential for both abstract and specific response classes, I think it all adds up to something that is a bit more sophisticated than your typical controller/view setup and takes a small investment in understanding. I think I'm still getting there, but I'm starting to get it.

And maybe a complete verbose example early in the docs somewhere could be useful as a reference.

This might be something that goes more into a tutorial than the regular docs, I'm not sure. But seeing upfront a fully verbose route setup without any shorthand might help to conceptualize how things work. This includes the things I've shown above like with the Response class. Some of the way generics are used is not intuitive until you've seen it working.