requests-unixsocket

Warnings

• breaking Updates to the upstream `requests` library can sometimes introduce breaking changes that affect `requests-unixsocket`, particularly related to internal adapter interfaces. While `requests-unixsocket` aims to maintain compatibility, rapid `requests` releases may temporarily break functionality.
  Fix: Ensure `requests-unixsocket` is updated to the latest version. If issues persist, consider pinning `requests` to a compatible older version or checking the `requests-unixsocket` GitHub issues for workarounds or upcoming fixes. A fork, `requests-unixsocket2`, emerged due to past incompatibilities, indicating this is a recurring concern.
• gotcha UNIX socket paths in URLs must be URL-percent-encoded (e.g., `/var/run/docker.sock` becomes `%2Fvar%2Frun%2Fdocker.sock`). Failure to encode correctly will result in incorrect URL parsing and connection errors.
  Fix: Always use `requests.compat.quote_plus()` or `urllib.parse.quote_plus()` to encode the UNIX socket path before constructing the `http+unix://` URL.
• gotcha Using `requests_unixsocket.monkeypatch()` globally alters the default behavior of `requests.get()` and `requests.Session()` (for default sessions). This can lead to unexpected side effects in other parts of an application or library that rely on standard `requests` behavior.
  Fix: Prefer creating an explicit `requests_unixsocket.Session()` instance for better isolation and control. If monkeypatching is necessary, limit its scope using a `with requests_unixsocket.monkeypatch():` context manager.
• gotcha The default timeout for `requests-unixsocket` connections (historically 60 seconds) might differ from the default behavior of `requests` (which has no default timeout). This can lead to unexpected blocking or timeout behavior if not explicitly set.
  Fix: Always explicitly set the `timeout` parameter in your `session.get()` or `session.post()` calls to ensure consistent and predictable behavior.
• gotcha Abstract namespace sockets (e.g., `http+unix://\0test_socket/`) are a Linux-specific feature and will not work on other operating systems like macOS or Windows.
  Fix: Ensure that if abstract namespace sockets are used, the application is deployed on a Linux environment. For cross-platform compatibility, prefer file-system based UNIX domain sockets or alternative IPC mechanisms.

Install

• pip install requests-unixsocket Install latest stable

Imports

• Session

  from requests_unixsocket import Session

  Use the specialized Session for explicit UNIX socket handling.
• monkeypatch

  import requests_unixsocket; requests_unixsocket.monkeypatch()

  Applies global monkeypatching for `requests.get()` to handle `http+unix://` URLs.

Quickstart

This quickstart demonstrates how to use `requests-unixsocket` in two ways: explicitly via `requests_unixsocket.Session` (recommended) and implicitly via `requests_unixsocket.monkeypatch()`. It attempts to connect to a common Docker UNIX domain socket to retrieve system information, handling potential connection errors. The socket path must be URL-percent-encoded.

import requests_unixsocket
import os

# Example for Docker daemon socket (adjust path if needed)
docker_socket_path = '/var/run/docker.sock' # or os.environ.get('DOCKER_SOCKET', '/var/run/docker.sock')

# Ensure the socket path exists for a runnable example
# In a real scenario, Docker or another service would create this.
# For this quickstart, we'll just check if it exists or use a dummy.
if not os.path.exists(docker_socket_path):
    print(f"Warning: Docker socket not found at {docker_socket_path}. Quickstart might not connect.")
    # Fallback to a non-existent path for structure, but it will fail.
    docker_socket_path = '/tmp/nonexistent_socket.sock'

# Explicit Session usage
session = requests_unixsocket.Session()
# The socket path must be percent-encoded in the URL host part
encoded_socket_path = requests_unixsocket.requests.compat.quote_plus(docker_socket_path)
url = f'http+unix://{encoded_socket_path}/info'

try:
    response = session.get(url, timeout=5)
    response.raise_for_status() # Raise an exception for HTTP errors
    print("Explicit Session usage successful!")
    print(f"Status Code: {response.status_code}")
    print(f"JSON Response Keys: {list(response.json().keys())[:5]}...")
except requests_unixsocket.requests.exceptions.ConnectionError as e:
    print(f"Connection Error: Could not connect to UNIX socket at {docker_socket_path}. Is a service listening there? (Error: {e})")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

# --- Alternative: Monkeypatching (affects global requests behavior) ---
# This is generally discouraged for libraries, but shown for completeness.
# with requests_unixsocket.monkeypatch():
#     try:
#         response_mp = requests_unixsocket.requests.get(url, timeout=5)
#         response_mp.raise_for_status()
#         print("\nMonkeypatching usage successful!")
#         print(f"Status Code: {response_mp.status_code}")
#         print(f"JSON Response Keys: {list(response_mp.json().keys())[:5]}...")
#     except requests_unixsocket.requests.exceptions.ConnectionError as e:
#         print(f"\nMonkeypatching Connection Error: Could not connect to UNIX socket at {docker_socket_path}. (Error: {e})")
#     except Exception as e:
#         print(f"\nAn unexpected error occurred with monkeypatching: {e}")