feat(API): Support http.HTTPStatus (a proof-of-concept prototype) (#1135)

[vytas7]

This is not a fully polished version, but rather a prototype. Old documentation, tutorials and Python docstrings are still largely intact. It would be awesome to first discuss the proposed changeset with @kgriffs and @jmvrbanac, and distill an acceptable technical solution first; I would be happy to contribute to the documentation afterwards.

The main design ideas laid out below are roughly in-line with the plan found in #1135 :

• Response.status shall be set to http.HTTPStatus, or its backport to older Python versions found in falcon.util.status_enum
• Integer status codes implicitly work too (both a convenience and logical inheritance wise: http.HTTPStatus subclasses an int via IntEnum)
• In the same falcon.util.status_enum, a base HTTP status enum class is defined similarly to http.HTTPStatus; that is used to support other non-standard status codes previously included in Falcon [1]
• Falcon usual status code constants are aliased to the new enum values [2], so a fair share of users could hopefully continue using most of their code as-is

Somewhat controversial ramifications:

• It may be cumbersome to define arbitrary codes; with the proposed changeset, one would need to resort to manually adding the string status to falcon.status_codes.COMBINED_STATUS_CODE lookup table. This could be made easier by either implementing support for legacy raw status, or probably by moving some part of this machinery to Response class, and documenting how and what to override to cram arbitrary status in; most probably both alternatives would come at a performance cost.

Other issues:

• Some of https://github.com/timothycrosley/hug tests are failing because of the same reason many Falcon tests were failing (assuming that falcon.HTTP_XXX are raw string statuses and using those values to check response status). @timothycrosley might now more, but from what I have seen in hug source code, it uses falcon.HTTP_XXX constants in a clean fashion, so it is just a problem with a couple of unit tests, not Hug API functionality.

1. As advertised!

What other framework has integrated support for 786 TRY IT NOW?

2. On Python 3:

>>> import falcon
>>> import http
>>> falcon.HTTP_404
<HTTPStatus.NOT_FOUND: 404>
>>> falcon.HTTP_404.phrase
'Not Found'
>>> int(falcon.HTTP_404)
404
>>> falcon.HTTP_FORBIDDEN
<HTTPStatus.FORBIDDEN: 403>
>>> falcon.HTTP_FORBIDDEN is http.HTTPStatus(403)
True

[vytas7]

An open question: could something like this be of use to API users?

[vytas7]

Suggestions for a better name are very welcome as this is a bit of a misnomer.

Technically HTTP status line includes HTTP protocol, so a full status would look like HTTP/1.1 404 Not Found.

Edit: maybe get_raw_http_status would look better?

[jgirardet]

Raw is better

[vytas7]

Killing this for now, I will try to port optimizations and design changes in small increments instead.