Single consistent name for status codes

[lovelydinosaur]

For consideration.

Currently we're exposing both httpx.StatusCodes and httpx.codes for working with status codes.

We're only documenting httpx.codes, and we probably only want a single canonical name here, right?

The documentation could also do with being expanded, at the very least in the API section.

Usages are like...

>>> httpx.codes.OK
<codes.OK: 200>
>>> httpx.codes.OK == 200
True
>>> httpx.codes.get_reason_phrase(200)
'OK'
>>> httpx.codes.is_error(400)
True
>>> httpx.codes.is_redirect(400)
False
>>> httpx.codes.is_client_error(400)
True
>>> httpx.codes.is_server_error(400)
False
>>> httpx.codes(200).phrase
'OK'
>>> httpx.codes(200).value
200

[jcugat]

Yup, makes sense 👍

[jcugat]

There are some usages in the wild of StatusCode, but I guess we are fine breaking compatibility with this before 1.0 right?

[florimondmanca]

Sure, httpx.codes is the documented one for now, but...

I personally feel like httpx.StatusCode would be a less surprising and a more natural option...

I initially thought httpx.codes meant that we refactored things to have a codes.py module, with plain functions as well as a .__call__() function - but then realized that the latter is probably not valid Python?

Anyway, I mean that httpx.codes looks like a module access, while it actually refers to a standard enum. In my experience enums are generally named after the singular of what they refer to, hence httpx.StatusCode?

So that would give us:

httpx.StatusCode.OK
httpx.StatusCode(200)
httpx.StatusCode.is_client_error(400)

[florimondmanca]

I'm not absolute on either option though and pretty much bikeshedding at this point...

The important bit is that we should have a single status codes enum, that I agree. :)

Minimizing breaking changes on httpx.codes (even with a smooth deprecation path) is a strong contender as well.

[lovelydinosaur]

I've updated this with a more gentle deprecation of httpx.StatusCode.