[PR aio-libs#7733/3b68b2f3 backport][3.9] Fix, update, and improve cl…

…ient exceptions documentation (aio-libs#7737)

**This is a backport of PR aio-libs#7733 as merged into master
(3b68b2f).**

In the *Hierarchy of exceptions* section of the *Client Reference*
documentation:
- Fix `ServerConnectionError` indentation, denoting that it subclasses
`ClientConnectionError`, not `ClientOSError`
- Fix `ServerFingerprintMismatch` indentation, denoting that it
subclasses `ServerConnectionError`, not `ClientOSError`
- Normalize the formatting so as to consistently use two, rather than
three, spaces for indentation
- Normalize the formatting so as to consistently include a blank newline
between exceptions
- Order exceptions alphabetically
- Add `TooManyRedirects`
- Add `UnixClientConnectorError`

Also order the documentation of client exceptions alphabetically by
hierarchy

- [N/A] I think the code is well written
- [N/A] Unit tests for the changes exist
- [N/A] Documentation reflects the changes
- [N/A ] If you provide code modification, please add yourself to
`CONTRIBUTORS.txt`
  * The format is <Name> <Surname>.
  * Please keep alphabetical order, the file is sorted by names.
- [X] Add a new news fragment into the `CHANGES` folder
  * name it `<issue_id>.<type>` for example (588.bugfix)
* if you don't have an `issue_id` change it to the pr id after creating
the pr
  * ensure type is one of the following:
    * `.feature`: Signifying a new feature.
    * `.bugfix`: Signifying a bug fix.
    * `.doc`: Signifying a documentation improvement.
    * `.removal`: Signifying a deprecation or removal of public API.
* `.misc`: A ticket has been closed, but it is not of interest to users.
* Make sure to use full sentences with correct case and punctuation, for
example: "Fix issue with non-ascii contents in doctest text files."

Co-authored-by: Harmon <[email protected]>

CHANGES/7733.doc

@@ -0,0 +1 @@
+Fix, update, and improve client exceptions documentation.

docs/client_reference.rst

@@ -137,6 +137,22 @@ The client session supports the context manager protocol for self closing.
       requests where you need to handle responses with status 400 or
       higher.
 
+      You can also provide a coroutine which takes the response as an
+      argument and can raise an exception based on custom logic, e.g.::
+
+          async def custom_check(response):
+              if response.status not in {201, 202}:
+                  raise RuntimeError('expected either 201 or 202')
+              text = await response.text()
+              if 'apple pie' not in text:
+                  raise RuntimeError('I wanted to see "apple pie" in response')
+
+          client_session = aiohttp.ClientSession(raise_for_status=custom_check)
+          ...
+
+      As with boolean values, you're free to set this on the session and/or
+      overwrite it on a per-request basis.
+
    :param timeout: a :class:`ClientTimeout` settings structure, 300 seconds (5min)
         total timeout by default.
 
@@ -1316,7 +1332,7 @@ Response object
       Reading from the stream may raise
       :exc:`aiohttp.ClientPayloadError` if the response object is
       closed before response receives all data or in case if any
-      transfer encoding related errors like malformed chunked
+      transfer encoding related errors like misformed chunked
       encoding of broken compression data.
 
    .. attribute:: cookies
@@ -2238,17 +2254,6 @@ Connection errors
 
    Derived from :exc:`ServerConnectionError` and :exc:`asyncio.TimeoutError`
 
-.. class:: ConnectionTimeoutError
-
-   Connection timeout on request: e.g. read timeout.
-
-   Derived from :exc:`ServerTimeoutError`
-
-.. class:: SocketTimeoutError
-
-   Reading from socket timeout.
-
-   Derived from :exc:`ServerTimeoutError`
 
 Hierarchy of exceptions
 ^^^^^^^^^^^^^^^^^^^^^^^
@@ -2279,10 +2284,6 @@ Hierarchy of exceptions
 
       * :exc:`ServerTimeoutError`
 
-        * :exc:`ConnectionTimeoutError`
-
-        * :exc:`SocketTimeoutError`
-
   * :exc:`ClientPayloadError`
 
   * :exc:`ClientResponseError`