Introduce `httpx.SSLError` exception

Originally opened by @pquentin on 2024-10-18 10:51:21 in encode/httpx

• Initially raised as discussion https://github.com/encode/httpx/discussions/3214#discussioncomment-10830925

httpcore 1.0.6 was released with a change that now maps SSLError to httpcore.ConnectError. But I'm realizing now that this change only affects asyncio (with and without anyio). All other backends (sync, trio with and without anyio) already raised httpx.ConnectError. The current behavior is consistent across backends, as is shown by the following tests:

import asyncio
import contextlib
import traceback

import anyio
import httpx
import pytest
import trio


def sync_bad_ssl():
    client = httpx.Client()
    client.get("https://tls-v1-0.badssl.com:1010")


async def bad_ssl():
    client = httpx.AsyncClient()
    await client.get("https://tls-v1-0.badssl.com:1010")


def test_sync_bad_ssl():
    with pytest.raises(httpx.ConnectError):
        sync_bad_ssl()

# Fails with httpcore<1.0.6
`@pytest`.mark.asyncio
async def test_bad_ssl_asyncio():
    with pytest.raises(httpx.ConnectError):
        await bad_ssl()


`@pytest`.mark.trio
async def test_bad_ssl_trio():
    with pytest.raises(httpx.ConnectError):
        await bad_ssl()

# Fails with httpcore<1.0.6 and anyio_backend=asyncio
`@pytest`.mark.parametrize("anyio_backend", ["asyncio", "trio"])
`@pytest`.mark.anyio
async def test_bad_ssl_anyio():
    with pytest.raises(httpx.ConnectError):
        await bad_ssl()

However, it's not consistent with other HTTP libraries out there:

• aiohttp raises aiohttp.client_exceptions.ClientSSLError
• requests raises requests.exceptions.SSLError
• urllib3 raises urllib3.exceptions.SSLError

As mentioned by Tom in the discussion, httpx should also be raising httpx.SSLError (a new subclass of httpx.RequestError), which would make it easier for downstream users to switch to httpx.

Start by tracing the existing exception hierarchy and the SSL failure paths exercised by test_sync_bad_ssl, test_bad_ssl_asyncio, test_bad_ssl_trio, and test_bad_ssl_anyio. Done means SSL failures consistently raise a new httpx.SSLError subclass of httpx.RequestError across the listed backends, with tests covering that behavior.