We are currently solving the following issue within our repository. Here is the issue text:
--- BEGIN ISSUE ---
Document the exception hierarchy 
We've put a stack of great work into this for 0.14 - let's also show it off.

--- END ISSUE ---

Below are some code segments, each from a relevant file. One or more of these files may contain bugs.
--- BEGIN FILES ---
Path: `httpx/_exceptions.py`
Content:
```
1 """
2 Our exception hierarchy:
3 
4 * HTTPError
5   x RequestError
6     + TransportError
7       - TimeoutException
8         · ConnectTimeout
9         · ReadTimeout
10         · WriteTimeout
11         · PoolTimeout
12       - NetworkError
13         · ConnectError
14         · ReadError
15         · WriteError
16         · CloseError
17       - ProtocolError
18         · LocalProtocolError
19         · RemoteProtocolError
20       - ProxyError
21       - UnsupportedProtocol
22     + DecodingError
23     + TooManyRedirects
24     + RequestBodyUnavailable
25   x HTTPStatusError
26 * NotRedirectResponse
27 * CookieConflict
28 * StreamError
29   x StreamConsumed
30   x ResponseNotRead
31   x RequestNotRead
32   x ResponseClosed
33 """
34 import contextlib
35 import typing
36 
37 import httpcore
38 
39 if typing.TYPE_CHECKING:
40     from ._models import Request, Response  # pragma: nocover
41 
42 
43 class HTTPError(Exception):
44     """
45     Base class for `RequestError` and `HTTPStatusError`.
46 
47     Useful for `try...except` blocks when issuing a request,
48     and then calling .raise_for_status().
49 
50     For example:
51 
52     try:
53         response = httpx.get("https://www.example.com")
54         response.raise_for_status()
55     except httpx.HTTPError as exc:
56         print(f"HTTP Exception for {exc.request.url} - {exc.message}")
57     """
58 
59     def __init__(self, message: str, *, request: "Request") -> None:
60         super().__init__(message)
61         self.request = request
62 
63 
64 class RequestError(HTTPError):
65     """
66     Base class for all exceptions that may occur when issuing a `.request()`.
67     """
68 
69     def __init__(self, message: str, *, request: "Request") -> None:
70         super().__init__(message, request=request)
71 
72 
73 class TransportError(RequestError):
74     """
75     Base class for all exceptions that are mapped from the httpcore API.
76     """
77 
78 
79 # Timeout exceptions...
80 
81 
82 class TimeoutException(TransportError):
83     """
84     The base class for timeout errors.
85 
86     An operation has timed out.
87     """
88 
89 
90 class ConnectTimeout(TimeoutException):
91     """
92     Timed out while connecting to the host.
93     """
94 
95 
96 class ReadTimeout(TimeoutException):
97     """
98     Timed out while receiving data from the host.
99     """
100 
101 
102 class WriteTimeout(TimeoutException):
103     """
104     Timed out while sending data to the host.
105     """
106 
107 
108 class PoolTimeout(TimeoutException):
109     """
110     Timed out waiting to acquire a connection from the pool.
111     """
112 
113 
114 # Core networking exceptions...
115 
116 
117 class NetworkError(TransportError):
118     """
119     The base class for network-related errors.
120 
121     An error occurred while interacting with the network.
122     """
123 
124 
125 class ReadError(NetworkError):
126     """
127     Failed to receive data from the network.
128     """
129 
130 
131 class WriteError(NetworkError):
132     """
133     Failed to send data through the network.
134     """
135 
136 
137 class ConnectError(NetworkError):
138     """
139     Failed to establish a connection.
140     """
141 
142 
143 class CloseError(NetworkError):
144     """
145     Failed to close a connection.
146     """
147 
148 
149 # Other transport exceptions...
150 
151 
152 class ProxyError(TransportError):
153     """
154     An error occurred while proxying a request.
155     """
156 
157 
158 class UnsupportedProtocol(TransportError):
159     """
160     Attempted to make a request to an unsupported protocol.
161 
162     For example issuing a request to `ftp://www.example.com`.
163     """
164 
165 
166 class ProtocolError(TransportError):
167     """
168     The protocol was violated.
169     """
170 
171 
172 class LocalProtocolError(ProtocolError):
173     """
174     A protocol was violated by the client.
175 
176     For example if the user instantiated a `Request` instance explicitly,
177     failed to include the mandatory `Host:` header, and then issued it directly
178     using `client.send()`.
179     """
180 
181 
182 class RemoteProtocolError(ProtocolError):
183     """
184     The protocol was violated by the server.
185 
186     For exaample, returning malformed HTTP.
187     """
188 
189 
190 # Other request exceptions...
191 
192 
193 class DecodingError(RequestError):
194     """
195     Decoding of the response failed.
196     """
197 
198 
199 class TooManyRedirects(RequestError):
200     """
201     Too many redirects.
202     """
203 
204 
205 class RequestBodyUnavailable(RequestError):
206     """
207     Had to send the request again, but the request body was streaming, and is
208     no longer available.
209     """
210 
211 
212 # Client errors
213 
214 
215 class HTTPStatusError(HTTPError):
216     """
217     Response sent an error HTTP status.
218 
219     May be raised when calling `response.raise_for_status()`
220     """
221 
222     def __init__(
223         self, message: str, *, request: "Request", response: "Response"
224     ) -> None:
225         super().__init__(message, request=request)
226         self.response = response
227 
228 
229 class NotRedirectResponse(Exception):
230     """
231     Response was not a redirect response.
232 
233     May be raised if `response.next()` is called without first
234     properly checking `response.is_redirect`.
235     """
236 
237     def __init__(self, message: str) -> None:
238         super().__init__(message)
239 
240 
241 class CookieConflict(Exception):
242     """
243     Attempted to lookup a cookie by name, but multiple cookies existed.
244 
245     Can occur when calling `response.cookies.get(...)`.
246     """
247 
248     def __init__(self, message: str) -> None:
249         super().__init__(message)
250 
251 
252 # Stream exceptions...
253 
254 # These may occur as the result of a programming error, by accessing
255 # the request/response stream in an invalid manner.
256 
257 
258 class StreamError(Exception):
259     """
260     The base class for stream exceptions.
261 
262     The developer made an error in accessing the request stream in
263     an invalid way.
264     """
265 
266     def __init__(self, message: str) -> None:
267         super().__init__(message)
268 
269 
270 class StreamConsumed(StreamError):
271     """
272     Attempted to read or stream response content, but the content has already
273     been streamed.
274     """
275 
276     def __init__(self) -> None:
277         message = (
278             "Attempted to read or stream response content, but the content has "
279             "already been streamed."
280         )
281         super().__init__(message)
282 
283 
284 class ResponseNotRead(StreamError):
285     """
286     Attempted to access response content, without having called `read()`
287     after a streaming response.
288     """
289 
290     def __init__(self) -> None:
291         message = (
292             "Attempted to access response content, without having called `read()` "
293             "after a streaming response."
294         )
295         super().__init__(message)
296 
297 
298 class RequestNotRead(StreamError):
299     """
300     Attempted to access request content, without having called `read()`.
301     """
302 
303     def __init__(self) -> None:
304         message = "Attempted to access request content, without having called `read()`."
305         super().__init__(message)
306 
307 
308 class ResponseClosed(StreamError):
309     """
310     Attempted to read or stream response content, but the request has been
311     closed.
312     """
313 
314     def __init__(self) -> None:
315         message = (
316             "Attempted to read or stream response content, but the request has "
317             "been closed."
318         )
319         super().__init__(message)
320 
321 
322 # The `InvalidURL` class is no longer required. It was being used to enforce only
323 # 'http'/'https' URLs being requested, but is now treated instead at the
324 # transport layer using `UnsupportedProtocol()`.`
325 
326 # We are currently still exposing this class, but it will be removed in 1.0.
327 InvalidURL = UnsupportedProtocol
328 
329 
330 @contextlib.contextmanager
331 def map_exceptions(
332     mapping: typing.Mapping[typing.Type[Exception], typing.Type[Exception]],
333     **kwargs: typing.Any,
334 ) -> typing.Iterator[None]:
335     try:
336         yield
337     except Exception as exc:
338         mapped_exc = None
339 
340         for from_exc, to_exc in mapping.items():
341             if not isinstance(exc, from_exc):
342                 continue
343             # We want to map to the most specific exception we can find.
344             # Eg if `exc` is an `httpcore.ReadTimeout`, we want to map to
345             # `httpx.ReadTimeout`, not just `httpx.TimeoutException`.
346             if mapped_exc is None or issubclass(to_exc, mapped_exc):
347                 mapped_exc = to_exc
348 
349         if mapped_exc is None:
350             raise
351 
352         message = str(exc)
353         raise mapped_exc(message, **kwargs) from None  # type: ignore
354 
355 
356 HTTPCORE_EXC_MAP = {
357     httpcore.TimeoutException: TimeoutException,
358     httpcore.ConnectTimeout: ConnectTimeout,
359     httpcore.ReadTimeout: ReadTimeout,
360     httpcore.WriteTimeout: WriteTimeout,
361     httpcore.PoolTimeout: PoolTimeout,
362     httpcore.NetworkError: NetworkError,
363     httpcore.ConnectError: ConnectError,
364     httpcore.ReadError: ReadError,
365     httpcore.WriteError: WriteError,
366     httpcore.CloseError: CloseError,
367     httpcore.ProxyError: ProxyError,
368     httpcore.UnsupportedProtocol: UnsupportedProtocol,
369     httpcore.ProtocolError: ProtocolError,
370     httpcore.LocalProtocolError: LocalProtocolError,
371     httpcore.RemoteProtocolError: RemoteProtocolError,
372 }
373
```
--- END FILES ---

Please first localize the bug based on the issue statement, and then generate a patch according to the `git diff` format fenced by three backticks.

Here is an example:

```diff
diff --git a/examples/server_async.py b/examples/server_async.py
--- a/examples/server_async.py
+++ b/examples/server_async.py
@@ -313,4 +313,4 @@
 
 
 if __name__ == "__main__":
-    asyncio.run(run_async_server("."), debug=True)
+    asyncio.run(run_async_server(), debug=True)
diff --git a/examples/server_sync.py b/examples/server_sync.py
--- a/examples/server_sync.py
+++ b/examples/server_sync.py
@@ -313,5 +313,5 @@
 
 
 if __name__ == "__main__":
-    server = run_sync_server(".")
+    server = run_sync_server()
     server.shutdown()

```

diff --git a/httpx/_exceptions.py b/httpx/_exceptions.py
--- a/httpx/_exceptions.py
+++ b/httpx/_exceptions.py
@@ -45,15 +45,17 @@
     Base class for `RequestError` and `HTTPStatusError`.
 
     Useful for `try...except` blocks when issuing a request,
-    and then calling .raise_for_status().
+    and then calling `.raise_for_status()`.
 
     For example:
 
+    ```
     try:
         response = httpx.get("https://www.example.com")
         response.raise_for_status()
     except httpx.HTTPError as exc:
         print(f"HTTP Exception for {exc.request.url} - {exc.message}")
+    ```
     """
 
     def __init__(self, message: str, *, request: "Request") -> None:
@@ -72,7 +74,9 @@
 
 class TransportError(RequestError):
     """
-    Base class for all exceptions that are mapped from the httpcore API.
+    Base class for all exceptions that occur at the level of the Transport API.
+
+    All of these exceptions also have an equivelent mapping in `httpcore`.
     """
 
 
@@ -151,7 +155,7 @@
 
 class ProxyError(TransportError):
     """
-    An error occurred while proxying a request.
+    An error occurred while establishing a proxy connection.
     """
 
 
@@ -192,7 +196,7 @@
 
 class DecodingError(RequestError):
     """
-    Decoding of the response failed.
+    Decoding of the response failed, due to a malformed encoding.
     """
 
 
@@ -214,7 +218,7 @@
 
 class HTTPStatusError(HTTPError):
     """
-    Response sent an error HTTP status.
+    The response had an error HTTP status of 4xx or 5xx.
 
     May be raised when calling `response.raise_for_status()`
     """

{"golden_diff": "diff --git a/httpx/_exceptions.py b/httpx/_exceptions.py\n--- a/httpx/_exceptions.py\n+++ b/httpx/_exceptions.py\n@@ -45,15 +45,17 @@\n     Base class for `RequestError` and `HTTPStatusError`.\n \n     Useful for `try...except` blocks when issuing a request,\n-    and then calling .raise_for_status().\n+    and then calling `.raise_for_status()`.\n \n     For example:\n \n+    ```\n     try:\n         response = httpx.get(\"https://www.example.com\")\n         response.raise_for_status()\n     except httpx.HTTPError as exc:\n         print(f\"HTTP Exception for {exc.request.url} - {exc.message}\")\n+    ```\n     \"\"\"\n \n     def __init__(self, message: str, *, request: \"Request\") -> None:\n@@ -72,7 +74,9 @@\n \n class TransportError(RequestError):\n     \"\"\"\n-    Base class for all exceptions that are mapped from the httpcore API.\n+    Base class for all exceptions that occur at the level of the Transport API.\n+\n+    All of these exceptions also have an equivelent mapping in `httpcore`.\n     \"\"\"\n \n \n@@ -151,7 +155,7 @@\n \n class ProxyError(TransportError):\n     \"\"\"\n-    An error occurred while proxying a request.\n+    An error occurred while establishing a proxy connection.\n     \"\"\"\n \n \n@@ -192,7 +196,7 @@\n \n class DecodingError(RequestError):\n     \"\"\"\n-    Decoding of the response failed.\n+    Decoding of the response failed, due to a malformed encoding.\n     \"\"\"\n \n \n@@ -214,7 +218,7 @@\n \n class HTTPStatusError(HTTPError):\n     \"\"\"\n-    Response sent an error HTTP status.\n+    The response had an error HTTP status of 4xx or 5xx.\n \n     May be raised when calling `response.raise_for_status()`\n     \"\"\"\n", "issue": "Document the exception hierarchy \nWe've put a stack of great work into this for 0.14 - let's also show it off.\n", "before_files": [{"content": "\"\"\"\nOur exception hierarchy:\n\n* HTTPError\n  x RequestError\n    + TransportError\n      - TimeoutException\n        \u00b7 ConnectTimeout\n        \u00b7 ReadTimeout\n        \u00b7 WriteTimeout\n        \u00b7 PoolTimeout\n      - NetworkError\n        \u00b7 ConnectError\n        \u00b7 ReadError\n        \u00b7 WriteError\n        \u00b7 CloseError\n      - ProtocolError\n        \u00b7 LocalProtocolError\n        \u00b7 RemoteProtocolError\n      - ProxyError\n      - UnsupportedProtocol\n    + DecodingError\n    + TooManyRedirects\n    + RequestBodyUnavailable\n  x HTTPStatusError\n* NotRedirectResponse\n* CookieConflict\n* StreamError\n  x StreamConsumed\n  x ResponseNotRead\n  x RequestNotRead\n  x ResponseClosed\n\"\"\"\nimport contextlib\nimport typing\n\nimport httpcore\n\nif typing.TYPE_CHECKING:\n    from ._models import Request, Response  # pragma: nocover\n\n\nclass HTTPError(Exception):\n    \"\"\"\n    Base class for `RequestError` and `HTTPStatusError`.\n\n    Useful for `try...except` blocks when issuing a request,\n    and then calling .raise_for_status().\n\n    For example:\n\n    try:\n        response = httpx.get(\"https://www.example.com\")\n        response.raise_for_status()\n    except httpx.HTTPError as exc:\n        print(f\"HTTP Exception for {exc.request.url} - {exc.message}\")\n    \"\"\"\n\n    def __init__(self, message: str, *, request: \"Request\") -> None:\n        super().__init__(message)\n        self.request = request\n\n\nclass RequestError(HTTPError):\n    \"\"\"\n    Base class for all exceptions that may occur when issuing a `.request()`.\n    \"\"\"\n\n    def __init__(self, message: str, *, request: \"Request\") -> None:\n        super().__init__(message, request=request)\n\n\nclass TransportError(RequestError):\n    \"\"\"\n    Base class for all exceptions that are mapped from the httpcore API.\n    \"\"\"\n\n\n# Timeout exceptions...\n\n\nclass TimeoutException(TransportError):\n    \"\"\"\n    The base class for timeout errors.\n\n    An operation has timed out.\n    \"\"\"\n\n\nclass ConnectTimeout(TimeoutException):\n    \"\"\"\n    Timed out while connecting to the host.\n    \"\"\"\n\n\nclass ReadTimeout(TimeoutException):\n    \"\"\"\n    Timed out while receiving data from the host.\n    \"\"\"\n\n\nclass WriteTimeout(TimeoutException):\n    \"\"\"\n    Timed out while sending data to the host.\n    \"\"\"\n\n\nclass PoolTimeout(TimeoutException):\n    \"\"\"\n    Timed out waiting to acquire a connection from the pool.\n    \"\"\"\n\n\n# Core networking exceptions...\n\n\nclass NetworkError(TransportError):\n    \"\"\"\n    The base class for network-related errors.\n\n    An error occurred while interacting with the network.\n    \"\"\"\n\n\nclass ReadError(NetworkError):\n    \"\"\"\n    Failed to receive data from the network.\n    \"\"\"\n\n\nclass WriteError(NetworkError):\n    \"\"\"\n    Failed to send data through the network.\n    \"\"\"\n\n\nclass ConnectError(NetworkError):\n    \"\"\"\n    Failed to establish a connection.\n    \"\"\"\n\n\nclass CloseError(NetworkError):\n    \"\"\"\n    Failed to close a connection.\n    \"\"\"\n\n\n# Other transport exceptions...\n\n\nclass ProxyError(TransportError):\n    \"\"\"\n    An error occurred while proxying a request.\n    \"\"\"\n\n\nclass UnsupportedProtocol(TransportError):\n    \"\"\"\n    Attempted to make a request to an unsupported protocol.\n\n    For example issuing a request to `ftp://www.example.com`.\n    \"\"\"\n\n\nclass ProtocolError(TransportError):\n    \"\"\"\n    The protocol was violated.\n    \"\"\"\n\n\nclass LocalProtocolError(ProtocolError):\n    \"\"\"\n    A protocol was violated by the client.\n\n    For example if the user instantiated a `Request` instance explicitly,\n    failed to include the mandatory `Host:` header, and then issued it directly\n    using `client.send()`.\n    \"\"\"\n\n\nclass RemoteProtocolError(ProtocolError):\n    \"\"\"\n    The protocol was violated by the server.\n\n    For exaample, returning malformed HTTP.\n    \"\"\"\n\n\n# Other request exceptions...\n\n\nclass DecodingError(RequestError):\n    \"\"\"\n    Decoding of the response failed.\n    \"\"\"\n\n\nclass TooManyRedirects(RequestError):\n    \"\"\"\n    Too many redirects.\n    \"\"\"\n\n\nclass RequestBodyUnavailable(RequestError):\n    \"\"\"\n    Had to send the request again, but the request body was streaming, and is\n    no longer available.\n    \"\"\"\n\n\n# Client errors\n\n\nclass HTTPStatusError(HTTPError):\n    \"\"\"\n    Response sent an error HTTP status.\n\n    May be raised when calling `response.raise_for_status()`\n    \"\"\"\n\n    def __init__(\n        self, message: str, *, request: \"Request\", response: \"Response\"\n    ) -> None:\n        super().__init__(message, request=request)\n        self.response = response\n\n\nclass NotRedirectResponse(Exception):\n    \"\"\"\n    Response was not a redirect response.\n\n    May be raised if `response.next()` is called without first\n    properly checking `response.is_redirect`.\n    \"\"\"\n\n    def __init__(self, message: str) -> None:\n        super().__init__(message)\n\n\nclass CookieConflict(Exception):\n    \"\"\"\n    Attempted to lookup a cookie by name, but multiple cookies existed.\n\n    Can occur when calling `response.cookies.get(...)`.\n    \"\"\"\n\n    def __init__(self, message: str) -> None:\n        super().__init__(message)\n\n\n# Stream exceptions...\n\n# These may occur as the result of a programming error, by accessing\n# the request/response stream in an invalid manner.\n\n\nclass StreamError(Exception):\n    \"\"\"\n    The base class for stream exceptions.\n\n    The developer made an error in accessing the request stream in\n    an invalid way.\n    \"\"\"\n\n    def __init__(self, message: str) -> None:\n        super().__init__(message)\n\n\nclass StreamConsumed(StreamError):\n    \"\"\"\n    Attempted to read or stream response content, but the content has already\n    been streamed.\n    \"\"\"\n\n    def __init__(self) -> None:\n        message = (\n            \"Attempted to read or stream response content, but the content has \"\n            \"already been streamed.\"\n        )\n        super().__init__(message)\n\n\nclass ResponseNotRead(StreamError):\n    \"\"\"\n    Attempted to access response content, without having called `read()`\n    after a streaming response.\n    \"\"\"\n\n    def __init__(self) -> None:\n        message = (\n            \"Attempted to access response content, without having called `read()` \"\n            \"after a streaming response.\"\n        )\n        super().__init__(message)\n\n\nclass RequestNotRead(StreamError):\n    \"\"\"\n    Attempted to access request content, without having called `read()`.\n    \"\"\"\n\n    def __init__(self) -> None:\n        message = \"Attempted to access request content, without having called `read()`.\"\n        super().__init__(message)\n\n\nclass ResponseClosed(StreamError):\n    \"\"\"\n    Attempted to read or stream response content, but the request has been\n    closed.\n    \"\"\"\n\n    def __init__(self) -> None:\n        message = (\n            \"Attempted to read or stream response content, but the request has \"\n            \"been closed.\"\n        )\n        super().__init__(message)\n\n\n# The `InvalidURL` class is no longer required. It was being used to enforce only\n# 'http'/'https' URLs being requested, but is now treated instead at the\n# transport layer using `UnsupportedProtocol()`.`\n\n# We are currently still exposing this class, but it will be removed in 1.0.\nInvalidURL = UnsupportedProtocol\n\n\n@contextlib.contextmanager\ndef map_exceptions(\n    mapping: typing.Mapping[typing.Type[Exception], typing.Type[Exception]],\n    **kwargs: typing.Any,\n) -> typing.Iterator[None]:\n    try:\n        yield\n    except Exception as exc:\n        mapped_exc = None\n\n        for from_exc, to_exc in mapping.items():\n            if not isinstance(exc, from_exc):\n                continue\n            # We want to map to the most specific exception we can find.\n            # Eg if `exc` is an `httpcore.ReadTimeout`, we want to map to\n            # `httpx.ReadTimeout`, not just `httpx.TimeoutException`.\n            if mapped_exc is None or issubclass(to_exc, mapped_exc):\n                mapped_exc = to_exc\n\n        if mapped_exc is None:\n            raise\n\n        message = str(exc)\n        raise mapped_exc(message, **kwargs) from None  # type: ignore\n\n\nHTTPCORE_EXC_MAP = {\n    httpcore.TimeoutException: TimeoutException,\n    httpcore.ConnectTimeout: ConnectTimeout,\n    httpcore.ReadTimeout: ReadTimeout,\n    httpcore.WriteTimeout: WriteTimeout,\n    httpcore.PoolTimeout: PoolTimeout,\n    httpcore.NetworkError: NetworkError,\n    httpcore.ConnectError: ConnectError,\n    httpcore.ReadError: ReadError,\n    httpcore.WriteError: WriteError,\n    httpcore.CloseError: CloseError,\n    httpcore.ProxyError: ProxyError,\n    httpcore.UnsupportedProtocol: UnsupportedProtocol,\n    httpcore.ProtocolError: ProtocolError,\n    httpcore.LocalProtocolError: LocalProtocolError,\n    httpcore.RemoteProtocolError: RemoteProtocolError,\n}\n", "path": "httpx/_exceptions.py"}], "after_files": [{"content": "\"\"\"\nOur exception hierarchy:\n\n* HTTPError\n  x RequestError\n    + TransportError\n      - TimeoutException\n        \u00b7 ConnectTimeout\n        \u00b7 ReadTimeout\n        \u00b7 WriteTimeout\n        \u00b7 PoolTimeout\n      - NetworkError\n        \u00b7 ConnectError\n        \u00b7 ReadError\n        \u00b7 WriteError\n        \u00b7 CloseError\n      - ProtocolError\n        \u00b7 LocalProtocolError\n        \u00b7 RemoteProtocolError\n      - ProxyError\n      - UnsupportedProtocol\n    + DecodingError\n    + TooManyRedirects\n    + RequestBodyUnavailable\n  x HTTPStatusError\n* NotRedirectResponse\n* CookieConflict\n* StreamError\n  x StreamConsumed\n  x ResponseNotRead\n  x RequestNotRead\n  x ResponseClosed\n\"\"\"\nimport contextlib\nimport typing\n\nimport httpcore\n\nif typing.TYPE_CHECKING:\n    from ._models import Request, Response  # pragma: nocover\n\n\nclass HTTPError(Exception):\n    \"\"\"\n    Base class for `RequestError` and `HTTPStatusError`.\n\n    Useful for `try...except` blocks when issuing a request,\n    and then calling `.raise_for_status()`.\n\n    For example:\n\n    ```\n    try:\n        response = httpx.get(\"https://www.example.com\")\n        response.raise_for_status()\n    except httpx.HTTPError as exc:\n        print(f\"HTTP Exception for {exc.request.url} - {exc.message}\")\n    ```\n    \"\"\"\n\n    def __init__(self, message: str, *, request: \"Request\") -> None:\n        super().__init__(message)\n        self.request = request\n\n\nclass RequestError(HTTPError):\n    \"\"\"\n    Base class for all exceptions that may occur when issuing a `.request()`.\n    \"\"\"\n\n    def __init__(self, message: str, *, request: \"Request\") -> None:\n        super().__init__(message, request=request)\n\n\nclass TransportError(RequestError):\n    \"\"\"\n    Base class for all exceptions that occur at the level of the Transport API.\n\n    All of these exceptions also have an equivelent mapping in `httpcore`.\n    \"\"\"\n\n\n# Timeout exceptions...\n\n\nclass TimeoutException(TransportError):\n    \"\"\"\n    The base class for timeout errors.\n\n    An operation has timed out.\n    \"\"\"\n\n\nclass ConnectTimeout(TimeoutException):\n    \"\"\"\n    Timed out while connecting to the host.\n    \"\"\"\n\n\nclass ReadTimeout(TimeoutException):\n    \"\"\"\n    Timed out while receiving data from the host.\n    \"\"\"\n\n\nclass WriteTimeout(TimeoutException):\n    \"\"\"\n    Timed out while sending data to the host.\n    \"\"\"\n\n\nclass PoolTimeout(TimeoutException):\n    \"\"\"\n    Timed out waiting to acquire a connection from the pool.\n    \"\"\"\n\n\n# Core networking exceptions...\n\n\nclass NetworkError(TransportError):\n    \"\"\"\n    The base class for network-related errors.\n\n    An error occurred while interacting with the network.\n    \"\"\"\n\n\nclass ReadError(NetworkError):\n    \"\"\"\n    Failed to receive data from the network.\n    \"\"\"\n\n\nclass WriteError(NetworkError):\n    \"\"\"\n    Failed to send data through the network.\n    \"\"\"\n\n\nclass ConnectError(NetworkError):\n    \"\"\"\n    Failed to establish a connection.\n    \"\"\"\n\n\nclass CloseError(NetworkError):\n    \"\"\"\n    Failed to close a connection.\n    \"\"\"\n\n\n# Other transport exceptions...\n\n\nclass ProxyError(TransportError):\n    \"\"\"\n    An error occurred while establishing a proxy connection.\n    \"\"\"\n\n\nclass UnsupportedProtocol(TransportError):\n    \"\"\"\n    Attempted to make a request to an unsupported protocol.\n\n    For example issuing a request to `ftp://www.example.com`.\n    \"\"\"\n\n\nclass ProtocolError(TransportError):\n    \"\"\"\n    The protocol was violated.\n    \"\"\"\n\n\nclass LocalProtocolError(ProtocolError):\n    \"\"\"\n    A protocol was violated by the client.\n\n    For example if the user instantiated a `Request` instance explicitly,\n    failed to include the mandatory `Host:` header, and then issued it directly\n    using `client.send()`.\n    \"\"\"\n\n\nclass RemoteProtocolError(ProtocolError):\n    \"\"\"\n    The protocol was violated by the server.\n\n    For exaample, returning malformed HTTP.\n    \"\"\"\n\n\n# Other request exceptions...\n\n\nclass DecodingError(RequestError):\n    \"\"\"\n    Decoding of the response failed, due to a malformed encoding.\n    \"\"\"\n\n\nclass TooManyRedirects(RequestError):\n    \"\"\"\n    Too many redirects.\n    \"\"\"\n\n\nclass RequestBodyUnavailable(RequestError):\n    \"\"\"\n    Had to send the request again, but the request body was streaming, and is\n    no longer available.\n    \"\"\"\n\n\n# Client errors\n\n\nclass HTTPStatusError(HTTPError):\n    \"\"\"\n    The response had an error HTTP status of 4xx or 5xx.\n\n    May be raised when calling `response.raise_for_status()`\n    \"\"\"\n\n    def __init__(\n        self, message: str, *, request: \"Request\", response: \"Response\"\n    ) -> None:\n        super().__init__(message, request=request)\n        self.response = response\n\n\nclass NotRedirectResponse(Exception):\n    \"\"\"\n    Response was not a redirect response.\n\n    May be raised if `response.next()` is called without first\n    properly checking `response.is_redirect`.\n    \"\"\"\n\n    def __init__(self, message: str) -> None:\n        super().__init__(message)\n\n\nclass CookieConflict(Exception):\n    \"\"\"\n    Attempted to lookup a cookie by name, but multiple cookies existed.\n\n    Can occur when calling `response.cookies.get(...)`.\n    \"\"\"\n\n    def __init__(self, message: str) -> None:\n        super().__init__(message)\n\n\n# Stream exceptions...\n\n# These may occur as the result of a programming error, by accessing\n# the request/response stream in an invalid manner.\n\n\nclass StreamError(Exception):\n    \"\"\"\n    The base class for stream exceptions.\n\n    The developer made an error in accessing the request stream in\n    an invalid way.\n    \"\"\"\n\n    def __init__(self, message: str) -> None:\n        super().__init__(message)\n\n\nclass StreamConsumed(StreamError):\n    \"\"\"\n    Attempted to read or stream response content, but the content has already\n    been streamed.\n    \"\"\"\n\n    def __init__(self) -> None:\n        message = (\n            \"Attempted to read or stream response content, but the content has \"\n            \"already been streamed.\"\n        )\n        super().__init__(message)\n\n\nclass ResponseNotRead(StreamError):\n    \"\"\"\n    Attempted to access response content, without having called `read()`\n    after a streaming response.\n    \"\"\"\n\n    def __init__(self) -> None:\n        message = (\n            \"Attempted to access response content, without having called `read()` \"\n            \"after a streaming response.\"\n        )\n        super().__init__(message)\n\n\nclass RequestNotRead(StreamError):\n    \"\"\"\n    Attempted to access request content, without having called `read()`.\n    \"\"\"\n\n    def __init__(self) -> None:\n        message = \"Attempted to access request content, without having called `read()`.\"\n        super().__init__(message)\n\n\nclass ResponseClosed(StreamError):\n    \"\"\"\n    Attempted to read or stream response content, but the request has been\n    closed.\n    \"\"\"\n\n    def __init__(self) -> None:\n        message = (\n            \"Attempted to read or stream response content, but the request has \"\n            \"been closed.\"\n        )\n        super().__init__(message)\n\n\n# The `InvalidURL` class is no longer required. It was being used to enforce only\n# 'http'/'https' URLs being requested, but is now treated instead at the\n# transport layer using `UnsupportedProtocol()`.`\n\n# We are currently still exposing this class, but it will be removed in 1.0.\nInvalidURL = UnsupportedProtocol\n\n\n@contextlib.contextmanager\ndef map_exceptions(\n    mapping: typing.Mapping[typing.Type[Exception], typing.Type[Exception]],\n    **kwargs: typing.Any,\n) -> typing.Iterator[None]:\n    try:\n        yield\n    except Exception as exc:\n        mapped_exc = None\n\n        for from_exc, to_exc in mapping.items():\n            if not isinstance(exc, from_exc):\n                continue\n            # We want to map to the most specific exception we can find.\n            # Eg if `exc` is an `httpcore.ReadTimeout`, we want to map to\n            # `httpx.ReadTimeout`, not just `httpx.TimeoutException`.\n            if mapped_exc is None or issubclass(to_exc, mapped_exc):\n                mapped_exc = to_exc\n\n        if mapped_exc is None:\n            raise\n\n        message = str(exc)\n        raise mapped_exc(message, **kwargs) from None  # type: ignore\n\n\nHTTPCORE_EXC_MAP = {\n    httpcore.TimeoutException: TimeoutException,\n    httpcore.ConnectTimeout: ConnectTimeout,\n    httpcore.ReadTimeout: ReadTimeout,\n    httpcore.WriteTimeout: WriteTimeout,\n    httpcore.PoolTimeout: PoolTimeout,\n    httpcore.NetworkError: NetworkError,\n    httpcore.ConnectError: ConnectError,\n    httpcore.ReadError: ReadError,\n    httpcore.WriteError: WriteError,\n    httpcore.CloseError: CloseError,\n    httpcore.ProxyError: ProxyError,\n    httpcore.UnsupportedProtocol: UnsupportedProtocol,\n    httpcore.ProtocolError: ProtocolError,\n    httpcore.LocalProtocolError: LocalProtocolError,\n    httpcore.RemoteProtocolError: RemoteProtocolError,\n}\n", "path": "httpx/_exceptions.py"}]}