[orsenthil]

The urlopen() documentation says only that it raises URLError on protocol errors. In practice, exceptions raised while reading or parsing the HTTP response come from http.client without being wrapped. These include:

• http.client.HTTPException subclasses such as BadStatusLine. These are not OSError subclasses, so even except OSError misses them.
• OSError subclasses such as TimeoutError (the server doesn't respond within timeout) and RemoteDisconnected.

ValueError is also raised for a URL with no scheme.

This happens because AbstractHTTPHandler.do_open() wraps OSError in URLError only around h.request(), not around h.getresponse().

Earlier discussion on the issue (Antoine Pitrou, Martin Panter) and the related issues gh-53069, gh-66986 and gh-69819 settled on documenting this rather than adding more wrapping, which would break existing code. This PR changes only the documentation.

🤖 Generated with Claude Code

---

Helpful reproducer for this.

import socket, threading, time, urllib.request, urllib.error

def serve(reply, delay=0):
    s = socket.socket(); s.bind(("127.0.0.1", 0)); s.listen(1)
    def run():
        c, _ = s.accept(); c.recv(65536)
        time.sleep(delay)
        if reply is not None: c.sendall(reply)
        time.sleep(0.5); c.close(); s.close()
    threading.Thread(target=run, daemon=True).start()
    return f"http://127.0.0.1:{s.getsockname()[1]}/"

cases = {
  "read timeout during getresponse": (None, 2, 0.5),
  "bad status line":                 (b"GARBAGE\r\n\r\n", 0, 5),
  "invalid status code":             (b"HTTP/1.1 1000 OK\r\n\r\n", 0, 5),
  "empty reply (RemoteDisconnected)":(b"", 0, 5),
  "too many headers":                (b"HTTP/1.1 200 OK\r\n" + b"X: y\r\n"*200 + b"\r\n", 0, 5),
}
for name, (reply, delay, tmo) in cases.items():
    url = serve(reply, delay)
    try:
        urllib.request.urlopen(url, timeout=tmo).read()
        print(f"{name:36} -> no error")
    except Exception as e:
        print(f"{name:36} -> {type(e).__module__}.{type(e).__qualname__}"
              f"  isURLError={isinstance(e, urllib.error.URLError)}  isOSError={isinstance(e, OSError)}")
# connection refused (connect phase) and bad scheme/value
for name, url in [("connection refused", "http://127.0.0.1:1/"), ("unknown scheme", "foo://x"), ("no scheme", "example.com")]:
    try: urllib.request.urlopen(url, timeout=2)
    except Exception as e:
        print(f"{name:36} -> {type(e).__module__}.{type(e).__qualname__}  isURLError={isinstance(e, urllib.error.URLError)}")

 ./python -I repro.py 
read timeout during getresponse      -> builtins.TimeoutError  isURLError=False  isOSError=True
bad status line                      -> http.client.BadStatusLine  isURLError=False  isOSError=False
invalid status code                  -> http.client.BadStatusLine  isURLError=False  isOSError=False
empty reply (RemoteDisconnected)     -> http.client.RemoteDisconnected  isURLError=False  isOSError=True
too many headers                     -> http.client.HTTPException  isURLError=False  isOSError=False
connection refused                   -> urllib.error.URLError  isURLError=True
unknown scheme                       -> urllib.error.URLError  isURLError=True
no scheme                            -> builtins.ValueError  isURLError=False

• Issue: urllib.request.urlopen leaks exceptions from socket and httplib.client #57945

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #35474467 | 📁 Comparing abb69d4 against main (d7ea5ba)

  🔍 Preview build  

1 file changed

± library/urllib.request.html

[miss-islington-app]

Thanks @orsenthil for the PR 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

[miss-islington-app]

Thanks @orsenthil for the PR 🌮🎉.. I'm working now to backport this PR to: 3.15.
🐍🍒⛏🤖

[bedevere-app]

GH-160831 is a backport of this pull request to the 3.14 branch.

[bedevere-app]

GH-160832 is a backport of this pull request to the 3.15 branch.