From abb69d4266c9efbc38e1d23b71bfdf9c208bca11 Mon Sep 17 00:00:00 2001 From: Senthil Kumaran Date: Wed, 28 Oct 2026 08:46:39 -0700 Subject: [PATCH] gh-57945: Document exceptions not wrapped by urlopen() Exceptions raised while reading or parsing the HTTP response, such as http.client.HTTPException subclasses and OSError subclasses like TimeoutError, propagate from urlopen() without being wrapped in URLError. Document this, and that ValueError is raised for an invalid URL. Co-Authored-By: Claude Opus 5.5 --- Doc/library/urllib.request.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst index e1581e213c5ca88..9a75f4986e1a3a9 100644 --- a/Doc/library/urllib.request.rst +++ b/Doc/library/urllib.request.rst @@ -68,6 +68,16 @@ The :mod:`!urllib.request` module defines the following functions: Raises :exc:`~urllib.error.URLError` on protocol errors. + Exceptions raised while reading or parsing an HTTP response are not + wrapped in :exc:`~urllib.error.URLError` and propagate unchanged. + These include subclasses of :exc:`http.client.HTTPException`, such as + :exc:`~http.client.BadStatusLine` for a malformed status line, and + subclasses of :exc:`OSError`, such as :exc:`TimeoutError` if the server + does not respond within *timeout* seconds, or + :exc:`~http.client.RemoteDisconnected` if the server closes the + connection without sending a response. :exc:`ValueError` is raised if + *url* is not a valid URL. + Note that ``None`` may be returned if no handler handles the request (though the default installed global :class:`OpenerDirector` uses :class:`UnknownHandler` to ensure this never happens).