aio-libs
Feature Request: Documentation around exceptions
As #4064 shows the current system of exceptions is rather complicated, leading to recommendations like building tuples of various components to try and catch everything. For people who are not familiar with the aiohttp internals this can be a bit of work. Adding a few examples to the docs and making it clear which exceptions are thrown in which circumstances would make it easier for developers to use this library.
This is not unique to aiohttp, this is quite basic Python knowledge. See the stardard Python exception hierarchy, and the Handling Exceptions section of the Python tutorial.
We don't need to repeat this in the aiohttp documentation.
I would say that aiohttp.ClientError, asyncio.TimeoutError and OSError should cover your basic needs.
The set is pretty close to the mentioned requests page.
Other libraries have no problem with this.
The requests documentation has simply not exposed you to their hierarchy. The full exceptions list only names Timeout as a base class, but their classes are organised using inheritance just like the aiohttp exceptions. This is the tree of exceptions in the requests library:
RequestException (with IOError)
+-- ChunkedEncodingError
+-- ConnectionError
| +-- ConnectTimeout (with Timeout)
| +-- ProxyError
| +-- SSLError
+-- ContentDecodingError (with urllib3.exceptions.HTTPError)
+-- HTTPError
+-- InvalidHeader (with ValueError)
+-- InvalidSchema (with ValueError)
+-- InvalidURL (with ValueError)
| +-- InvalidProxyURL
+-- MissingSchema (with ValueError)
+-- RetryError
+-- StreamConsumedError (with TypeError)
+-- TooManyRedirects
+-- Timeout
| +-- ConnectionTimeOut (with ConnectionError)
| +-- ReadTimeout
+-- UnrewindableBodyError
+-- URLRequired
I included some subclasses more than once when they have been derived from multiple base classes, e.g. ConnectionTimeOut which subclasses both ConnectionError and Timeout. See requests.exceptions.
requests itself wraps urllib3, see their list of exceptions, whose tree is like this:
HTTPError
+-- DecodeError
+-- HeaderParsingError
+-- IncompleteRead (with http.client.IncompleteRead)
+-- InvalidHeader
+-- LocationValueError (with ValueError)
| +-- LocationParseError
+-- PoolError
| +-- ClosedPoolError
| +-- EmptyPoolError
| +-- NewConnectionError (with ConnectTimeoutError)
| +-- RequestError
| +-- MaxRetryError
| +-- HostChangedError
| +-- ReadTimeoutError (with TimeoutError)
| +-- TimeoutStateError
+-- ProtocolError (also available under the old name, ConnectionError)
| +-- ResponseNotChunked (with ValueError)
+-- ProxyError
+-- ResponseError
+-- SSLError
+-- TimeoutError
| +-- ConnectTimeoutError
| | +-- NewConnectionError (with PoolError)
| +-- ReadTimeoutError (with RequestError)
+-- UnrewindableBodyError
ProxySchemeUnknown (with AssertionError and ValueError)
See the urllib3.exceptions module.
All that happened is that you picked a wrong exception to try and catch; the same could have happened to you in any of the other HTTP client libraries. I'm sorry if I gave too detailed advice on what kinds of exceptions you could catch.
I've honestly never seen such resistance to simply adding documentation, but I get the point and won't be opening any issues in this project going forward.
Have you a concrete idea for PR? Did you read http://docs.aiohttp.org/en/stable/client_reference.html#client-exceptions ?
@mjpieters and I are trying to say that simple chapter like requests have is not complete and doesn't reflect the full list of available exceptions. The reference is much more complex, and aiohttp has such list already.
I don't have a concrete idea yet, as I generally like to open issues and see if teams are receptive to ideas before I commit my time to make a PR (whether it's documentation or code). I generally devote at least one weekend a month to open source contributions though, and keep track of my open issues to see where I might best put my efforts.