Public Access
140 lines
4.4 KiB
Python
140 lines
4.4 KiB
Python
#!/usr/bin/env python3
|
|
"""Utilities for handling API response values and base HTTP API client.
|
|
|
|
This module provides two categories of utilities:
|
|
|
|
1. **Response helpers** — :func:`is_truthy` and :func:`is_falsy` handle
|
|
APIs that return boolean values as strings (``"true"``, ``"false"``)
|
|
rather than native JSON booleans.
|
|
|
|
2. **Base API client** — :class:`APIClient` provides a reusable base
|
|
class for HTTP API clients with consistent timeout handling, header
|
|
propagation, and automatic raising on 4xx/5xx responses.
|
|
|
|
Usage::
|
|
|
|
from devx.utils.api import APIClient, is_truthy
|
|
|
|
class MyClient(APIClient):
|
|
def __init__(self):
|
|
super().__init__(
|
|
base_url="https://api.example.com",
|
|
headers={"Authorization": "Bearer token"},
|
|
)
|
|
|
|
if not is_truthy(config.get("EnableOpenServer")):
|
|
raise ValueError("EnableOpenServer not enabled")
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import requests
|
|
|
|
|
|
class APIClient:
|
|
"""Base class for HTTP API clients.
|
|
|
|
Subclasses set ``base_url``, ``headers``, and optionally ``auth`` in
|
|
their constructor, then use :meth:`_request` or the convenience
|
|
methods (:meth:`get`, :meth:`post`, etc.) to make requests.
|
|
|
|
All requests raise :class:`requests.HTTPError` on 4xx/5xx responses
|
|
via :meth:`requests.Response.raise_for_status`.
|
|
"""
|
|
|
|
def __init__(
|
|
self,
|
|
base_url: str,
|
|
headers: dict,
|
|
timeout: int = 30,
|
|
verify: bool = True,
|
|
auth: tuple[str, str] | None = None,
|
|
) -> None:
|
|
"""Initialize the API client.
|
|
|
|
Args:
|
|
base_url: Base URL for the API (trailing slash stripped).
|
|
headers: Default headers sent with every request.
|
|
timeout: Request timeout in seconds.
|
|
verify: Whether to verify TLS certificates.
|
|
auth: Optional ``(username, password)`` tuple for basic auth.
|
|
"""
|
|
self.base_url = base_url.rstrip("/")
|
|
self.headers = headers
|
|
self.timeout = timeout
|
|
self.verify = verify
|
|
self.auth = auth
|
|
|
|
def _request(self, method: str, path: str, **kwargs) -> requests.Response:
|
|
"""Execute an HTTP request against the API.
|
|
|
|
The URL is constructed as ``{base_url}{path}``. Default timeout,
|
|
verify, auth, and headers are applied but can be overridden via
|
|
``kwargs``.
|
|
|
|
Raises:
|
|
requests.HTTPError: On 4xx/5xx response status codes.
|
|
"""
|
|
url = f"{self.base_url}{path}"
|
|
kwargs.setdefault("timeout", self.timeout)
|
|
kwargs.setdefault("verify", self.verify)
|
|
if self.auth is not None:
|
|
kwargs.setdefault("auth", self.auth)
|
|
resp = requests.request(method, url, headers=self.headers, **kwargs) # noqa: S113
|
|
resp.raise_for_status()
|
|
return resp
|
|
|
|
def get(self, path: str, **kwargs) -> requests.Response:
|
|
"""Send a GET request."""
|
|
return self._request("GET", path, **kwargs)
|
|
|
|
def post(self, path: str, **kwargs) -> requests.Response:
|
|
"""Send a POST request."""
|
|
return self._request("POST", path, **kwargs)
|
|
|
|
def put(self, path: str, **kwargs) -> requests.Response:
|
|
"""Send a PUT request."""
|
|
return self._request("PUT", path, **kwargs)
|
|
|
|
def delete(self, path: str, **kwargs) -> requests.Response:
|
|
"""Send a DELETE request."""
|
|
return self._request("DELETE", path, **kwargs)
|
|
|
|
def patch(self, path: str, **kwargs) -> requests.Response:
|
|
"""Send a PATCH request."""
|
|
return self._request("PATCH", path, **kwargs)
|
|
|
|
|
|
def is_truthy(value: str | bool | None) -> bool:
|
|
"""Check if an API config value is truthy.
|
|
|
|
The API may return strings (``"true"``/``"false"``) or native
|
|
booleans. This helper handles both.
|
|
|
|
Args:
|
|
value: The value to check (string, bool, or None).
|
|
|
|
Returns:
|
|
True if the value represents a truthy boolean.
|
|
"""
|
|
if isinstance(value, bool):
|
|
return value
|
|
return str(value).lower() == "true"
|
|
|
|
|
|
def is_falsy(value: str | bool | None) -> bool:
|
|
"""Check if an API config value is falsy.
|
|
|
|
The API may return strings (``"true"``/``"false"``) or native
|
|
booleans. This helper handles both.
|
|
|
|
Args:
|
|
value: The value to check (string, bool, or None).
|
|
|
|
Returns:
|
|
True if the value represents a falsy boolean.
|
|
"""
|
|
if isinstance(value, bool):
|
|
return not value
|
|
return str(value).lower() == "false"
|