Return values V1

[Tinche]

A very simple spec for return values from attrsapi handlers.

I'm avoiding the discussion of content types for now, since that discussion will be more complex and can be dealt with later.

Here's what an attrsapi handler may return:

• an instance of the framework response class (starlette.responses.Response, flask.Response, etc). This is an escape hatch if a user needs to return something that's not supported. This cannot be statically parsed so it won't show up in the OpenAPI schema
• str - will be passed to the framework response class as text, and probably UTF8 encoded by the framework (I think they all do that)
• bytes - will be passed to the framework directly
• None, or no annotation - no content is returned, status code 200
• an instance of an attrs class or dataclass - will be unstructured and JSON encoded, and then passed to the framework. Customizing this process to come later
• a tuple containing an integer literal and str | bytes | attrs | dataclass. The first type argument (the int literal) will be used as the status code, and the other processed as usual
• a union of such tuples, for multiple status codes

[Tinche]

I might have to add a possible return value to the list:

• a triple of (status code, response body, response headers). I think that about covers the all possible outputs of an HTTP handler. Response cookies are essentially response headers with some extra data, and redirects are a combination of a status code and a Location header.

If we weren't interested in OpenAPI compatibility this would be a breeze, but since we are we need to expose some metadata here statically. By that I mean, by analyzing the function return value signature we need to know the names of the headers we're returning and their types.

Let's say we want to return two headers, X-HEADER and TEST. (Dashes are common in headers but Python names don't support them.)

One option would be making the users define a class and return an instance of that.

@define
class MyHeaders:
    x_header: Annotated[str, Header('X-HEADER')]
    TEST: str

async def handler() -> tuple[Literal[200], None, MyHeaders]:
    return 200, None, MyHeaders("my value", "test")

This works fine, but I just find it annoying a class needs to be defined for each combination of headers.

So let's look at more... esoteric solutions.

One solution would be to, instead of a class, we make you return a tuple of tuples. The inner tuples contain the name of the header as a string literal, and the type of the value.

async def handler() -> tuple[Literal[200], None, tuple[tuple[Literal["X-HEADER", str]], tuple[Literal["TEST", str]]]]:
    return 200, None, (("X-HEADER", "my value"), ("TEST", "test"))

This works fine (and is type-checked by Mypy 0.920+), except the type signature is very hairy. It can be helped by some aliasing, like Hynek suggested.

from attrsapi.status import OK
XHEADER = "X-HEADER"
TEST = "TEST"

async def handler() -> tuple[OK, None, tuple[tuple[XHEADER, str], tuple[TEST, str]]:
    return OK, None, ((XHEADER, "my value"), (TEST, "test"))

And I guess a third alternative would be our old friend typing.Annotated.

from attrsapi.status import OK

async def handler() -> tuple[OK, None, tuple[Annotated[str, "X-HEADER"], Annotated[str, "TEST"]]]:
    return OK, None, ("my value", "test")

It's also a little more DRY.

[Tinche]

I think this is what FastAPI does: https://fastapi.tiangolo.com/advanced/response-headers/. I don't see how it can know the headers for OpenAPI without actually running the handler, so I'm guessing they don't support it entirely. I am too lazy ATM to set up a dummy project and test it out.

How would your suggestion work? This doesn't work:

@define
class Header(Generic[HN, T]):
    pass


async def handle() -> tuple[Literal[200], None, tuple[Header["X-HEADER", str]]]:  # mypy: Invalid type comment or annotation
    pass

[Tinche]

It works with a type alias, but again double tuples in the response:

Header = tuple[HN, T]


async def handle() -> tuple[
    Literal[200], None, tuple[Header[Literal["X-HEADER"], str]]
]:
    return 200, None, (("X-HEADER", "test"),)

Also I wouldn't call it Header since that would conflict with the request header, which I would define a little differently. So maybe RespHeader or ResponseHeader?

[hynek]

Hm is this maybe something that could be expressed more elegantly with a decorator or something? I mean we need a way to specify incoming headers too, no?

[Tinche]

My first plan was using a decorator, and I even implemented request headers that way. The problem with this approach is elsewhere, when you try wrapping the handlers in something else (like middleware!).

The goal is that by examining a function signature we can determine it's OpenAPI representation. This is made much easier if this information is in the type annotations, since there are decorator libraries for Python (wrapt) that allow middleware to be applied to a handler and to keep or add to a function signature. If we stick arbitrary data on the handler itself in dunder attributes, this won't work.

[hynek]

Hmmm are you sure that decorators don't break those annotations too?