feat: Add support for Docker Desktop socket locations on macOS

Docker Desktop for macOS v4.x+ changed the default socket location from
/var/run/docker.sock to ~/.docker/run/docker.sock. This caused
ConnectionError/FileNotFoundError when users didn't have DOCKER_HOST set.

This commit adds automatic socket discovery that checks multiple locations
in order of preference:
1. /var/run/docker.sock (traditional Linux/macOS location)
2. ~/.docker/run/docker.sock (Docker Desktop v4.x+ on macOS)
3. ~/.docker/desktop/docker.sock (older Docker Desktop location)

The implementation:
- Adds UNIX_SOCKET_PATHS list with known socket locations
- Adds _find_available_unix_socket() function for discovery
- Makes DEFAULT_UNIX_SOCKET dynamically computed at import time
- Falls back to /var/run/docker.sock if no socket exists

This only affects Unix/macOS; Windows continues to use named pipes.
DOCKER_HOST environment variable and Docker contexts still take precedence.

Fixes #3271

Author: halicki

docker/constants.py

@@ -1,3 +1,4 @@
+import os
 import sys
 
 from .version import __version__
@@ -11,7 +12,26 @@
 ]
 
 DEFAULT_HTTP_HOST = "127.0.0.1"
-DEFAULT_UNIX_SOCKET = "http+unix:///var/run/docker.sock"
+
+# Potential Unix socket locations in order of preference
+UNIX_SOCKET_PATHS = [
+    '/var/run/docker.sock',  # Traditional Linux/macOS location
+    os.path.expanduser('~/.docker/run/docker.sock'),  # Docker Desktop v4.x+ on macOS
+    os.path.expanduser('~/.docker/desktop/docker.sock'),  # Older Docker Desktop location
+]
+
+
+def _find_available_unix_socket():
+    """Find the first available Docker socket from known locations."""
+    for path in UNIX_SOCKET_PATHS:
+        if os.path.exists(path):
+            return f"http+unix://{path}"
+    # Fallback to traditional location even if it doesn't exist
+    return f"http+unix://{UNIX_SOCKET_PATHS[0]}"
+
+
+# Dynamic default socket - checks multiple locations
+DEFAULT_UNIX_SOCKET = _find_available_unix_socket()
 DEFAULT_NPIPE = 'npipe:////./pipe/docker_engine'
 
 BYTE_UNITS = {

tests/unit/client_test.py

@@ -10,6 +10,7 @@
     DEFAULT_DOCKER_API_VERSION,
     DEFAULT_MAX_POOL_SIZE,
     DEFAULT_TIMEOUT_SECONDS,
+    DEFAULT_UNIX_SOCKET,
     IS_WINDOWS_PLATFORM,
 )
 from docker.utils import kwargs_from_env
@@ -89,9 +90,11 @@ def test_default_pool_size_unix(self, mock_obj):
         client.ping()
 
         base_url = f"{client.api.base_url}/v{client.api._version}/_ping"
+        # Extract socket path from DEFAULT_UNIX_SOCKET (remove http+unix:// prefix)
+        socket_path = DEFAULT_UNIX_SOCKET.replace('http+unix://', '')
 
         mock_obj.assert_called_once_with(base_url,
-                                         "/var/run/docker.sock",
+                                         socket_path,
                                          60,
                                          maxsize=DEFAULT_MAX_POOL_SIZE
                                          )
@@ -125,9 +128,11 @@ def test_pool_size_unix(self, mock_obj):
         client.ping()
 
         base_url = f"{client.api.base_url}/v{client.api._version}/_ping"
+        # Extract socket path from DEFAULT_UNIX_SOCKET (remove http+unix:// prefix)
+        socket_path = DEFAULT_UNIX_SOCKET.replace('http+unix://', '')
 
         mock_obj.assert_called_once_with(base_url,
-                                         "/var/run/docker.sock",
+                                         socket_path,
                                          60,
                                          maxsize=POOL_SIZE
                                          )
@@ -198,9 +203,11 @@ def test_default_pool_size_from_env_unix(self, mock_obj):
         client.ping()
 
         base_url = f"{client.api.base_url}/v{client.api._version}/_ping"
+        # Extract socket path from DEFAULT_UNIX_SOCKET (remove http+unix:// prefix)
+        socket_path = DEFAULT_UNIX_SOCKET.replace('http+unix://', '')
 
         mock_obj.assert_called_once_with(base_url,
-                                         "/var/run/docker.sock",
+                                         socket_path,
                                          60,
                                          maxsize=DEFAULT_MAX_POOL_SIZE
                                          )
@@ -233,9 +240,11 @@ def test_pool_size_from_env_unix(self, mock_obj):
         client.ping()
 
         base_url = f"{client.api.base_url}/v{client.api._version}/_ping"
+        # Extract socket path from DEFAULT_UNIX_SOCKET (remove http+unix:// prefix)
+        socket_path = DEFAULT_UNIX_SOCKET.replace('http+unix://', '')
 
         mock_obj.assert_called_once_with(base_url,
-                                         "/var/run/docker.sock",
+                                         socket_path,
                                          60,
                                          maxsize=POOL_SIZE
                                          )