Type inference by decorator parameters instead of function refactoring

[cjllanwarne]

Hello and thanks for a great project!

I wondered whether there's any interest in support for type inference at the decorator level rather than by changing the return type of methods?

Right now I have a set of methods that I'd like to create a schema for, but refactoring them all to return APIResponse is going to be non-trivial for various reasons (see all the various routes in our front_end.py).

Some reasons include -

• Non-json return types
• StreamResponses from the APIs
• A set of decorators and helper functions that mutate the parameter lists and return types

It seems like it might be easier if there were a style of decoration that allowed us to document the parameters and return types without having to refactor the server code at all. Perhaps something like -

@SCHEMA.api(parameters=[], response=str)
@routes.get('/api/v1alpha/version')
async def rest_get_version(_) -> web.Response:
    return web.Response(text=version())

Right now I'm forced to refactor the code itself to look like -

@SCHEMA.api()
@routes.get('/api/v1alpha/version')
async def rest_get_version(_) -> APIResponse[str, Literal[200]]:
    return APIResponse(version())

This is easy enough in this case, but even here the version gets "json-ified" (see #39). It would be nice if I could document the API without having to make any refactors to the code itself.

Thank you!

[Dreamsorcerer]

I think this is really just a duplicate of your other issue. This might be the most sensible solution for non-json responses.

One of the primary goals of the library is to support strict static typing. So, for JSON responses, the APIResponse allows the return type to be checked accurately by type checkers (it's the only reason for the class to exist, as you can see from the code, it doesn't provide any runtime functionality other than calling json.dumps()). Using decorator parameters will lose any type checking here.

[cjllanwarne]

Thanks for such a quick reply!

I can totally see why starting from scratch, using APIResponse with strong type guarantees is super helpful anyway and you get documentation for free. In my case we have a whole mini ecosystem of helper functions built around web.Response and web.StreamingResponse that I'd rather not touch if I don't have to! And my primary goal is the schema documentation rather than adding in type validation.

I agree these two issues might be closely related (they both boil down to wanting to document an existing API I've inherited without having to change the existing responses (#39), and ideally without having to take on a medium sized refactor of the service code (this one)).

It sounds like #39 might gain some traction, but perhaps this one is outside the intended scope of the project?