Option to raise exception on error codes

[theFong]

Is your feature request related to a problem? Please describe.
In some cases, if an unexpected error code is returned (or even an expected error code), I would rather raise an exception than return None. This is because depending on the linter and adoption of type annotation in a code base I may not handle a None variable. In this case an exception raising status code, message or other meta data would be more useful to debug especially when using exception logging software like Sentry.

Describe the solution you'd like
I see a couple of interface possibilities if this feature would make sense to implement.

Add new functions with a must prefix:

• must_sync
• must_sync_detailed
• must_async
• must_async_detailed
  This is inspired by a Golang's pattern of prefixing "must" to functions which may panic. The main downside is the addition of 4 new methods.

Another solution would be to provide a raise_for_status method similar to python requests library on the Response object. This interface would allow the passing of args to specify raising in case of any error code or just unexpected ones. The side effect here is that like remembering to handle None you would have to remember to raise_for_status. This side effect exists when using the requests library so is not a big deal.

Describe alternatives you've considered
Currently in cases where I would like to fail hard, I have a wrapper function which takes a ..._detailed function and builds an exception with meta data if parsed is None. This works fine.

Interested in thoughts/discussion!

[dbanty]

I actually had the generated functions raising exceptions previously when there was an unexpected status code, but I took that out because of the lack of static checking for exceptions. As far as I've seen, there's no handy tool to tell you "hey this function could throw an exception but you aren't handling it" whereas having something be Optional means mypy will force you to check it.

I hesitate to add a bunch more functions for exactly the reason you point out - code bloat - but you're right that having to call raise_for_status (which httpx has as well) for every call wouldn't give you a much better developer experience than checking for None every time.

Is this the sort of thing that you would always want for a given client? Maybe it would be better to have this as a generator option? If set it could call raise_for_status internally on every httpx.Response? We could also make it a runtime setting on Client but, again, bloat.

[bowenwr]

There's also a dose of 1 in the way we internally use our SDK - most of our errors ARE unrecoverable and we let them crash on through and stop the script in its tracks.

[emann]

Just some thoughts about implementation:

We could also use an event handler on the internal httpx.Client itself:

# (from the docs)
def raise_on_4xx_5xx(response):
    response.raise_for_status()

client = httpx.Client(event_hooks={'response': [raise_on_4xx_5xx]})

but granted that makes the implementation httpx-specific, and AFAIK there's no way to do something similar in requests. Doing it directly on the Response objects wouldn't even be too bad in terms of code bloat, as we could just update _build_response to take the client as a parameter and call raise_for_status() accordingly:

def _build_response(*, client: Client, response: httpx.Response) -> Response[{{ return_string }}]:
    if client.raise_exceptions_on_bad_status_codes:
        # We'll probably want to raise our own Exception here that has the response object in it
        response.raise_for_status() 
    return Response(
        status_code=response.status_code,
        content=response.content,
        headers=response.headers,
        {% if parsed_responses %}
        parsed=_parse_response(response=response),
        {% else %}
        parsed=None,
        {% endif %}
    )

[dbanty]

If we do #202 (which we definitely intend to) then folks could do this themselves when they initialize the client. Or we could have the option in the generator add the hook in Client instead of on every endpoint!

[ramnes]

@emann Requests does have the same hook system:

session = requests.Session()
session.hooks = {
   'response': lambda r, *args, **kwargs: r.raise_for_status()
}

So yeah, #202 would do just well. :)

[dbanty]

Just a follow-up, #202 is done in the latest release, so you can add your own hook for raise_for_status().

[dbanty]

FYI I've seen enough interest in this that it's definitely something I'd like to implement as an option eventually. I've created issue #491 and added it to the long term 1.0 project. I don't anticipate this landing very soon, but it will happen 😁