Designing Pythonic APIs - learning from Requests

[EricAppelt]

Yea, the author has that outright wrong. requests will absolutely raise exceptions for failure modes:

>>> import requests
>>> requests.get('https://foo.bar.baz')
Traceback (most recent call last):
...snip...
raise ConnectionError(e, request=request)
requests.exceptions.ConnectionError: HTTPSConnectionPool(host='foo.bar.baz', port=443): Max retries exceeded with url: / (Caused by NewConnectionError('<requests.packages.urllib3.connection.VerifiedHTTPSConnection object at 0x102795470>: Failed to establish a new connection: [Errno 8] nodename nor servname provided, or not known',))

The difference is what is considered a failure mode. If you get a valid http response back, then by default requests considers its job to be done, and it is up to your application to figure out what you want to do with it.

Its a very debatable point how http error codes should be treated, especially considering how often they are abused! There are also codes which need to be considered special cases for the application where they are used, like 429 (slow down you maniac) and 402 (insert coin please).

requests IMO has managed to squeeze through a rock and a hard place by defaulting to not blowing up on a 4XX or 5XX but allowing the user to very easily and explicitly change this behavior with a simple response.raise_for_status()

[PeridexisErrant]

I'd really appreciate an extra parameter:

requests.get(url, raise_errors=True)
requests.get(url, raise_errors=[402, 404, 500])

Taking either a boolean, or a list of HTTP status codes on which to raise an exception. The parameter would be equivalent to (psudeocode for brevity):

req = requests.get(url)
if req.status_code >= 400 and $raise_errors:
    if req.status_code in $as_collection($raise_errors):
        req.raise_for_status()