Communicating status codes from handlers

[Tinche]

The OpenAPI generator needs to know the status codes handlers will produce, and it needs to know before the handler is actually executed.

According to the OpenAPI 3.0.3 spec, "documentation is expected to cover a successful operation response and any known errors".

[Tinche]

One option would be special casing return types of tuple(Literal[int], T).

async def post_handler() -> tuple[Literal[201], str]:
    return 201,  "success!"

If you might return several status codes:

async def post_handler() -> tuple[Literal[200], str] | tuple[Literal[201], str]:
    # the resource exists, so I'm returning 200
    return 200, "exists"
    # the resource doesn't exist, so I'm returning 201
    return 201, "created"

[Tinche]

I think it's technically correct to return essentially any integer from [100-599], some are standardized, some are up to you (see https://en.wikipedia.org/wiki/Hyper_Text_Coffee_Pot_Control_Protocol).

[hynek]

Using numbers is not very readable thought…would be nice to allow both?

[Tinche]

We could have some common aliases defined somewhere.

# In a module somewhere:
HTTP_200_OK = 200

reveal_type(HTTP_200_OK)  # Type of "HTTP_200_OK" is "Literal[200]"

That said, it doesn't look like an enum will work.

class HttpStatusCode(Enum, int):
        OK = 200

def test(i: Literal[200]):
        pass

test(HttpStatusCode.OK)  # error: Argument 1 to "test" has incompatible type "Literal[HttpStatusCode.OK]"; expected "Literal[200]"

So this enum would have to contain every status code we want to support, which doesn't seem like a good solution.

If we really want an enum (which would contain the most useful values), we would have to support both Literal[200] and Literal[HttpStatusCode.OK]. Which is doable, just a little annoying.

[Tinche]

I also considered just not making the class an enum:

class HttpStatusCode:
        OK = 200

but Mypy still treats HttpStatusCode.OK as int. Pyright, the type checker in VS Code, properly sees it as Literal[200] though, heh.

[hynek]

I didn't expect them to be interchangeable, I just thought it might be nice to support both. If you want to do the Literal-Aliasing fair enough tho!

[Tinche]

I have hit a snag working on this: python/mypy#11414

[Tinche]

I have hit a snag working on this: python/mypy#11414

This seems to be fixed on Mypy main, so will work in the next release!

[Tinche]

This has been implemented, but I feel we'll need to revisit this when we figure out how to set response content types and headers.