Enhance Error Messaging for Connection Failures

When making an HTTP request using the requests library, I encountered a connection failure. The error message provided was not very clear or actionable, especially for someone new to the library. Enhancing these error messages to provide more detailed and actionable information would significantly improve the developer experience.

Expected Result

I expected the error message to include more detailed information about the potential causes of the connection failure and suggestions for troubleshooting steps.

Actual Result

requests.exceptions.ConnectionError: HTTPSConnectionPool(host='osudle.com', port=443): Max retries exceeded with url: / (Caused by NewConnectionError('<urllib3.connection.HTTPSConnection object at 0x000001A9F6DB93C0>: Failed to establish a new connection: [WinError 10051] A socket operation was related to an unavailable network'))

Reproduction Steps

import requests

r = requests.get("http://osudle.com', timeout=20)

print(r.status_code)

System Information

$ python -m requests.help

python -m requests.help
{
  "chardet": {
    "version": null
  },
  "charset_normalizer": {
    "version": "2.0.12"
  },
  "cryptography": {
    "version": ""
  },
  "idna": {
    "version": "3.4"
  },
  "implementation": {
    "name": "CPython",
    "version": "3.10.4"
  },
  "platform": {
    "release": "10",
    "system": "Windows"
  },
  "pyOpenSSL": {
    "openssl_version": "",
    "version": null
  },
  "requests": {
    "version": "2.32.2"
  },
  "system_ssl": {
    "version": "101010ef"
  },
  "urllib3": {
    "version": "1.26.18"
  },
  "using_charset_normalizer": true,
  "using_pyopenssl": false
}

This command is only available on Requests v2.16.4 and greater. Otherwise, please provide some basic information about your system (Python version, operating system, &c).

psf / requests