standard-http 0.2.1__py3-none-any.whl

standard_http-0.2.1.dist-info/METADATA

@@ -0,0 +1,62 @@
+Metadata-Version: 2.5
+Name: standard-http
+Version: 0.2.1
+Summary: Async HTTP client and authentication helpers for Standard
+Project-URL: Documentation, https://appunni-m.github.io/python-standard/http/
+Project-URL: Repository, https://github.com/appunni-m/python-standard
+Author: Standard contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: async,authentication,http,httpx,standard
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: standard==0.2.1
+Description-Content-Type: text/markdown
+
+# standard-http
+
+`standard-http` adds an asynchronous HTTP client and authentication helpers to
+the `standard` Python library. Install the package to use the `std.http`
+import namespace:
+
+From this repository, install the core and HTTP projects together:
+
+```shell
+python -m pip install . packages/standard-http
+```
+
+After the add-on is published, install the distributions with
+`python -m pip install standard standard-http`.
+
+```python
+from std.http import AuthConfig, BearerAuth, HttpClient, RetryConfig
+
+client = HttpClient(
+    base_url="https://api.example.com/v1/",
+    auth_config=AuthConfig(auth=BearerAuth("your-token")),
+    retries=RetryConfig(max_attempts=3),
+)
+
+async with client:
+    response = await client.get("users", params={"active": "true"})
+    response.raise_for_status()
+    print(response.json())
+```
+
+The package also provides `BasicAuth`, `ApiKeyAuth`, `AuthBase`, `AuthConfig`,
+and Pydantic response helpers such as `get_model`. See the [HTTP guide](../../docs/http.md)
+for retry, timeout, token refresh, error, transport injection, and lifecycle
+behavior.
+
+The wheel contains only `std.http`; it does not bundle FastAPI, AWS, or other
+integration modules.

standard_http-0.2.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+std/http/__init__.py,sha256=Mp6N26w2emdqIhNQx4-KFq2kzFVf1-ypX0qz0XB4KIs,415
+std/http/auth.py,sha256=NrEkD-0dnx9eq_tqYTGc0RoeuQUs6xTu_VNRtTyidTo,3644
+std/http/client.py,sha256=neDnFEG1C21ChGBPASkiR66cYvyrdghGK0t6CHgjcKM,15974
+std/http/config.py,sha256=SLuqttlEp66qqoeC3vqfl-wotCh3HntCkrA-NlUHVJg,3826
+std/http/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+standard_http-0.2.1.dist-info/METADATA,sha256=wM1FAfOLM-B9rBuNcwYTQoj6rErhfmxoD0luMN6ZKtA,2176
+standard_http-0.2.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+standard_http-0.2.1.dist-info/licenses/LICENSE,sha256=RnyEKEDLRmbhyf36lr51oOrBm8qr4u2JYGHhg2Rcs7g,1073
+standard_http-0.2.1.dist-info/RECORD,,

standard_http-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

standard_http-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Standard contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

std/http/__init__.py

@@ -0,0 +1,16 @@
+"""Async HTTP client, retry configuration, and authentication helpers."""
+
+from std.http.auth import ApiKeyAuth, AuthBase, BasicAuth, BearerAuth
+from std.http.client import HttpClient, HttpClientError
+from std.http.config import AuthConfig, RetryConfig
+
+__all__ = [
+    "ApiKeyAuth",
+    "AuthBase",
+    "AuthConfig",
+    "BasicAuth",
+    "BearerAuth",
+    "HttpClient",
+    "HttpClientError",
+    "RetryConfig",
+]

std/http/auth.py

@@ -0,0 +1,96 @@
+"""Authentication handlers compatible with the Standard HTTP client."""
+
+from __future__ import annotations
+
+import base64
+
+import httpx
+
+
+class AuthBase:
+    """Base class for simple request-header authentication handlers."""
+
+    def auth_flow(self, request: httpx.Request) -> httpx.Request:
+        """Return the request unchanged; subclasses can add authentication headers."""
+        return request
+
+
+class BearerAuth(AuthBase):
+    """Add a bearer token to the ``Authorization`` request header."""
+
+    __slots__ = ("token",)
+
+    def __init__(self, token: str) -> None:
+        """Create bearer auth without including the secret in object representations."""
+        if not isinstance(token, str) or not token.strip():
+            raise ValueError("bearer token must be a non-empty string")
+        self.token = token
+
+    def auth_flow(self, request: httpx.Request) -> httpx.Request:
+        """Set the bearer authorization header on a request."""
+        request.headers["Authorization"] = f"Bearer {self.token}"
+        return request
+
+    def __repr__(self) -> str:
+        """Return a representation that does not disclose the bearer token."""
+        return "BearerAuth(token=[redacted])"
+
+
+class BasicAuth(AuthBase):
+    """Add HTTP Basic authentication using UTF-8 encoded credentials."""
+
+    __slots__ = ("username", "password")
+
+    def __init__(self, username: str, password: str) -> None:
+        """Create Basic auth without exposing credentials in object representations."""
+        if not isinstance(username, str) or not isinstance(password, str):
+            raise TypeError("username and password must be strings")
+        self.username = username
+        self.password = password
+
+    def auth_flow(self, request: httpx.Request) -> httpx.Request:
+        """Set the Basic authorization header on a request."""
+        credentials = f"{self.username}:{self.password}".encode()
+        encoded = base64.b64encode(credentials).decode("ascii")
+        request.headers["Authorization"] = f"Basic {encoded}"
+        return request
+
+    def __repr__(self) -> str:
+        """Return a representation that does not disclose either credential."""
+        return "BasicAuth(username=[redacted], password=[redacted])"
+
+
+class ApiKeyAuth(AuthBase):
+    """Add an API key to a configurable header, optionally with a prefix."""
+
+    __slots__ = ("api_key", "header_name", "prefix")
+
+    def __init__(
+        self,
+        api_key: str,
+        header_name: str = "X-API-Key",
+        prefix: str | None = None,
+    ) -> None:
+        """Create API-key auth with a custom header and optional value prefix."""
+        if not isinstance(api_key, str) or not api_key.strip():
+            raise ValueError("API key must be a non-empty string")
+        if not isinstance(header_name, str) or not header_name.strip():
+            raise ValueError("header name must be a non-empty string")
+        if prefix is not None and not isinstance(prefix, str):
+            raise TypeError("prefix must be a string or None")
+        self.api_key = api_key
+        self.header_name = header_name
+        self.prefix = prefix
+
+    def auth_flow(self, request: httpx.Request) -> httpx.Request:
+        """Set the API-key header on a request."""
+        value = f"{self.prefix} {self.api_key}" if self.prefix else self.api_key
+        request.headers[self.header_name] = value
+        return request
+
+    def __repr__(self) -> str:
+        """Return a representation that does not disclose the API key."""
+        return (
+            "ApiKeyAuth(api_key=[redacted], "
+            f"header_name={self.header_name!r}, prefix={self.prefix!r})"
+        )

std/http/client.py

@@ -0,0 +1,407 @@
+"""Async HTTP client with authentication, retries, and Pydantic response helpers."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import math
+import random
+from collections.abc import Mapping, Sequence
+from typing import Any, TypeVar
+
+import httpx
+from pydantic import BaseModel, ValidationError
+
+from std.http.auth import ApiKeyAuth, AuthBase, BearerAuth
+from std.http.config import AuthConfig, RetryConfig
+
+ModelT = TypeVar("ModelT", bound=BaseModel)
+_UNSET = object()
+_logger = logging.getLogger(__name__)
+
+
+class HttpClientError(Exception):
+    """A sanitized HTTP client failure with optional status and response context."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        response: httpx.Response | None = None,
+    ) -> None:
+        """Create an error without rendering request URLs, headers, or exception text."""
+        super().__init__(message)
+        self.status_code = status_code
+        self.response = response
+
+
+class _LegacyAuth(httpx.Auth):
+    """Adapt the historical one-request auth-flow contract to HTTPX auth."""
+
+    def __init__(self, auth: AuthBase) -> None:
+        self._auth = auth
+
+    def auth_flow(self, request: httpx.Request) -> Any:
+        yield self._auth.auth_flow(request)
+
+
+class HttpClient:
+    """Reusable asynchronous HTTP client with explicit retry and cleanup behavior.
+
+    ``retries`` accepts the historical integer form, interpreted as total attempts.
+    ``RetryConfig`` offers method, status, exception, backoff, and jitter controls.
+    """
+
+    def __init__(
+        self,
+        base_url: str = "",
+        timeout: float | httpx.Timeout | None = 10.0,
+        retries: int | RetryConfig | None = None,
+        auth_config: AuthConfig | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        verify_ssl: bool = True,
+        follow_redirects: bool = True,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        """Configure an HTTP client; the underlying connection pool is created lazily."""
+        if isinstance(retries, bool):
+            raise TypeError("retries cannot be a boolean")
+        if isinstance(retries, int):
+            if retries < 0:
+                raise ValueError("retries cannot be negative")
+            self.retry_config = RetryConfig(max_attempts=max(1, retries))
+        elif isinstance(retries, RetryConfig):
+            self.retry_config = retries
+        elif retries is None:
+            self.retry_config = RetryConfig()
+        else:
+            raise TypeError("retries must be an integer, RetryConfig, or None")
+
+        if timeout is not None and not isinstance(timeout, httpx.Timeout):
+            if isinstance(timeout, bool) or not isinstance(timeout, (int, float)):
+                raise TypeError("timeout must be a number, HTTPX Timeout, or None")
+            if not math.isfinite(timeout) or timeout < 0:
+                raise ValueError("timeout must be finite and non-negative")
+            timeout = httpx.Timeout(float(timeout))
+        if not isinstance(base_url, str):
+            raise TypeError("base_url must be a string")
+        if not isinstance(verify_ssl, bool) or not isinstance(follow_redirects, bool):
+            raise TypeError("verify_ssl and follow_redirects must be booleans")
+
+        self.base_url = base_url
+        self.timeout = timeout
+        self.auth_config = auth_config or AuthConfig()
+        self.default_headers = dict(default_headers or {})
+        self.verify_ssl = verify_ssl
+        self.follow_redirects = follow_redirects
+        self._transport = transport
+        self._client: httpx.AsyncClient | None = None
+        self._client_lock = asyncio.Lock()
+
+    async def __aenter__(self) -> HttpClient:
+        """Open the underlying HTTPX client and return this wrapper."""
+        await self._ensure_client()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> None:
+        """Close the underlying connection pool when leaving an async context."""
+        await self.close()
+
+    @property
+    async def client(self) -> httpx.AsyncClient:
+        """Return the lazily created HTTPX client for advanced use."""
+        return await self._ensure_client()
+
+    async def _ensure_client(self) -> httpx.AsyncClient:
+        """Create exactly one HTTPX client when concurrent requests start together."""
+        if self._client is not None:
+            return self._client
+        async with self._client_lock:
+            if self._client is None:
+                try:
+                    self._client = httpx.AsyncClient(
+                        base_url=self.base_url,
+                        timeout=self.timeout,
+                        verify=self.verify_ssl,
+                        follow_redirects=self.follow_redirects,
+                        headers=self.default_headers,
+                        transport=self._transport,
+                    )
+                except Exception:
+                    raise HttpClientError("HTTP client initialization failed") from None
+            return self._client
+
+    async def close(self) -> None:
+        """Close the connection pool; calling this method repeatedly is safe."""
+        async with self._client_lock:
+            client = self._client
+            self._client = None
+            if client is not None:
+                try:
+                    await client.aclose()
+                except Exception:
+                    raise HttpClientError("HTTP client cleanup failed") from None
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        headers: Mapping[str, str] | None = None,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """Send a request and return its response, including non-success statuses."""
+        if not isinstance(method, str) or not method.strip():
+            raise ValueError("method must be a non-empty string")
+        if not isinstance(url, str) or not url:
+            raise ValueError("url must be a non-empty string")
+
+        normalized_method = method.strip().upper()
+        request_kwargs = dict(kwargs)
+        per_request_auth = request_kwargs.pop("auth", _UNSET)
+        auth = self.auth_config.auth if per_request_auth is _UNSET else per_request_auth
+        client = await self._ensure_client()
+        attempts = self.retry_config.max_attempts
+        replayable = _request_body_is_replayable(request_kwargs)
+        refreshed = False
+
+        for attempt in range(attempts):
+            try:
+                request = client.build_request(
+                    normalized_method,
+                    url,
+                    headers=headers,
+                    **request_kwargs,
+                )
+                response = await client.send(request, auth=_as_httpx_auth(auth))
+            except Exception as error:
+                if (
+                    attempt + 1 < attempts
+                    and replayable
+                    and normalized_method in self.retry_config.retry_methods
+                    and _is_retryable_exception(error, self.retry_config)
+                ):
+                    _logger.warning(
+                        "HTTP %s request failed with %s; retrying attempt %d of %d",
+                        normalized_method,
+                        type(error).__name__,
+                        attempt + 2,
+                        attempts,
+                    )
+                    await self._sleep_before_retry(attempt)
+                    continue
+                raise HttpClientError(
+                    f"HTTP {normalized_method} request failed after {attempt + 1} attempt(s)"
+                ) from None
+
+            if (
+                response.status_code == 401
+                and not refreshed
+                and self.auth_config.refresh_callback is not None
+                and attempt + 1 < attempts
+                and replayable
+                and normalized_method in self.retry_config.retry_methods
+            ):
+                try:
+                    replacement = self.auth_config.refresh_callback()
+                    auth = _replace_auth_secret(auth, replacement)
+                except Exception:
+                    await response.aclose()
+                    raise HttpClientError(
+                        "HTTP authentication refresh failed",
+                        status_code=401,
+                        response=response,
+                    ) from None
+                refreshed = True
+                await response.aclose()
+                _logger.info(
+                    "HTTP %s authentication was refreshed after status 401", normalized_method
+                )
+                continue
+
+            if (
+                attempt + 1 < attempts
+                and replayable
+                and normalized_method in self.retry_config.retry_methods
+                and response.status_code in self.retry_config.retry_statuses
+            ):
+                _logger.warning(
+                    "HTTP %s returned status %d; retrying attempt %d of %d",
+                    normalized_method,
+                    response.status_code,
+                    attempt + 2,
+                    attempts,
+                )
+                await response.aclose()
+                await self._sleep_before_retry(attempt)
+                continue
+            return response
+
+        raise HttpClientError(
+            f"HTTP {normalized_method} request failed after {attempts} attempt(s)"
+        )
+
+    async def get(
+        self, url: str, headers: Mapping[str, str] | None = None, **kwargs: Any
+    ) -> httpx.Response:
+        """Send a GET request."""
+        return await self.request("GET", url, headers, **kwargs)
+
+    async def post(
+        self, url: str, headers: Mapping[str, str] | None = None, **kwargs: Any
+    ) -> httpx.Response:
+        """Send a POST request."""
+        return await self.request("POST", url, headers, **kwargs)
+
+    async def put(
+        self, url: str, headers: Mapping[str, str] | None = None, **kwargs: Any
+    ) -> httpx.Response:
+        """Send a PUT request."""
+        return await self.request("PUT", url, headers, **kwargs)
+
+    async def patch(
+        self, url: str, headers: Mapping[str, str] | None = None, **kwargs: Any
+    ) -> httpx.Response:
+        """Send a PATCH request."""
+        return await self.request("PATCH", url, headers, **kwargs)
+
+    async def delete(
+        self, url: str, headers: Mapping[str, str] | None = None, **kwargs: Any
+    ) -> httpx.Response:
+        """Send a DELETE request."""
+        return await self.request("DELETE", url, headers, **kwargs)
+
+    async def get_model(
+        self,
+        url: str,
+        response_model: type[ModelT],
+        headers: Mapping[str, str] | None = None,
+        **kwargs: Any,
+    ) -> ModelT:
+        """Send GET and validate its JSON response as a Pydantic model."""
+        return await self._send_model("GET", url, response_model, headers, **kwargs)
+
+    async def post_model(
+        self,
+        url: str,
+        response_model: type[ModelT],
+        headers: Mapping[str, str] | None = None,
+        **kwargs: Any,
+    ) -> ModelT:
+        """Send POST and validate its JSON response as a Pydantic model."""
+        return await self._send_model("POST", url, response_model, headers, **kwargs)
+
+    async def put_model(
+        self,
+        url: str,
+        response_model: type[ModelT],
+        headers: Mapping[str, str] | None = None,
+        **kwargs: Any,
+    ) -> ModelT:
+        """Send PUT and validate its JSON response as a Pydantic model."""
+        return await self._send_model("PUT", url, response_model, headers, **kwargs)
+
+    async def patch_model(
+        self,
+        url: str,
+        response_model: type[ModelT],
+        headers: Mapping[str, str] | None = None,
+        **kwargs: Any,
+    ) -> ModelT:
+        """Send PATCH and validate its JSON response as a Pydantic model."""
+        return await self._send_model("PATCH", url, response_model, headers, **kwargs)
+
+    async def delete_model(
+        self,
+        url: str,
+        response_model: type[ModelT],
+        headers: Mapping[str, str] | None = None,
+        **kwargs: Any,
+    ) -> ModelT:
+        """Send DELETE and validate its JSON response as a Pydantic model."""
+        return await self._send_model("DELETE", url, response_model, headers, **kwargs)
+
+    async def _send_model(
+        self,
+        method: str,
+        url: str,
+        response_model: type[ModelT],
+        headers: Mapping[str, str] | None,
+        **kwargs: Any,
+    ) -> ModelT:
+        """Validate a successful JSON response without leaking response details in errors."""
+        response = await self.request(method, url, headers, **kwargs)
+        if not response.is_success:
+            raise HttpClientError(
+                f"HTTP {method} returned status {response.status_code}",
+                status_code=response.status_code,
+                response=response,
+            )
+        try:
+            payload = response.json()
+            return response_model.model_validate(payload)
+        except (ValueError, ValidationError):
+            raise HttpClientError(
+                f"HTTP {method} response did not match {response_model.__name__}",
+                status_code=response.status_code,
+                response=response,
+            ) from None
+
+    async def _sleep_before_retry(self, attempt: int) -> None:
+        """Sleep for exponential backoff capped at one minute."""
+        factor = self.retry_config.backoff_factor
+        if factor == 0:
+            return
+        delay = min(factor * (2 ** min(attempt, 60)), 60.0)
+        if self.retry_config.jitter:
+            delay = min(delay * random.uniform(0.5, 1.5), 60.0)
+        await asyncio.sleep(delay)
+
+
+def _as_httpx_auth(auth: Any) -> httpx.Auth | None:
+    """Adapt the legacy auth handler to HTTPX while accepting native HTTPX auth."""
+    if auth is None:
+        return None
+    if isinstance(auth, httpx.Auth):
+        return auth
+    auth_flow = getattr(auth, "auth_flow", None)
+    if callable(auth_flow):
+        return _LegacyAuth(auth)
+    raise TypeError("auth must implement httpx.Auth or AuthBase.auth_flow")
+
+
+def _replace_auth_secret(auth: Any, secret: str) -> Any:
+    """Return a supported auth handler containing a refreshed token or API key."""
+    if not isinstance(secret, str) or not secret.strip():
+        raise ValueError("authentication refresh returned an empty secret")
+    if isinstance(auth, BearerAuth):
+        return BearerAuth(secret)
+    if isinstance(auth, ApiKeyAuth):
+        return ApiKeyAuth(secret, header_name=auth.header_name, prefix=auth.prefix)
+    raise TypeError("authentication refresh requires BearerAuth or ApiKeyAuth")
+
+
+def _is_retryable_exception(error: Exception, config: RetryConfig) -> bool:
+    """Retry transport errors by default and additional configured exception types."""
+    if isinstance(error, httpx.TransportError):
+        return True
+    return bool(config.retry_exceptions) and isinstance(error, tuple(config.retry_exceptions))
+
+
+def _request_body_is_replayable(kwargs: Mapping[str, Any]) -> bool:
+    """Avoid replaying generators and open streams that are exhausted by the first send."""
+    return all(_value_is_replayable(value) for value in kwargs.values())
+
+
+def _value_is_replayable(value: Any) -> bool:
+    """Return whether a request argument can be safely used to build a second request."""
+    if value is None or isinstance(value, (str, bytes, bytearray, memoryview, int, float, bool)):
+        return True
+    if isinstance(value, BaseModel):
+        return _value_is_replayable(value.model_dump())
+    if hasattr(value, "read"):
+        return False
+    if isinstance(value, Mapping):
+        return all(_value_is_replayable(item) for item in value.values())
+    if isinstance(value, Sequence):
+        return all(_value_is_replayable(item) for item in value)
+    return False

std/http/config.py

@@ -0,0 +1,99 @@
+"""Typed configuration for HTTP request retries and authentication."""
+
+from collections.abc import Callable
+from math import isfinite
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class RetryConfig(BaseModel):
+    """Control which HTTP responses and errors are retried."""
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    max_attempts: int = Field(
+        default=3, ge=1, description="Maximum total attempts, including the first"
+    )
+    retry_statuses: list[int] = Field(
+        default_factory=lambda: [500, 502, 503, 504],
+        description="HTTP status codes eligible for a retry",
+    )
+    retry_methods: list[str] = Field(
+        default_factory=lambda: ["GET", "HEAD", "PUT", "DELETE", "OPTIONS", "TRACE"],
+        description="HTTP methods eligible for a retry",
+    )
+    backoff_factor: float = Field(default=0.5, ge=0, description="Base delay in seconds")
+    jitter: bool = Field(default=True, description="Apply bounded random jitter to retry delays")
+    retry_exceptions: list[type[BaseException]] = Field(
+        default_factory=list,
+        description="Additional exception classes eligible for retries",
+    )
+
+    @field_validator("retry_statuses")
+    @classmethod
+    def validate_retry_statuses(cls, values: list[int]) -> list[int]:
+        """Require valid HTTP status codes and remove duplicates in input order."""
+        unique_values: list[int] = []
+        for status in values:
+            if isinstance(status, bool) or not 100 <= status <= 599:
+                raise ValueError("retry statuses must be integers from 100 through 599")
+            if status not in unique_values:
+                unique_values.append(status)
+        return unique_values
+
+    @field_validator("retry_methods")
+    @classmethod
+    def normalize_retry_methods(cls, values: list[str]) -> list[str]:
+        """Normalize method names and reject empty values."""
+        methods: list[str] = []
+        for method in values:
+            if not method or not method.strip():
+                raise ValueError("retry methods cannot be empty")
+            normalized = method.strip().upper()
+            if normalized not in methods:
+                methods.append(normalized)
+        return methods
+
+    @field_validator("retry_exceptions")
+    @classmethod
+    def validate_retry_exceptions(
+        cls, values: list[type[BaseException]]
+    ) -> list[type[BaseException]]:
+        """Require exception classes rather than instances or arbitrary objects."""
+        for exception_type in values:
+            if not isinstance(exception_type, type) or not issubclass(
+                exception_type, BaseException
+            ):
+                raise ValueError("retry_exceptions must contain exception classes")
+        return values
+
+    @field_validator("backoff_factor")
+    @classmethod
+    def validate_backoff_factor(cls, value: float) -> float:
+        """Require a finite delay factor so a bad config cannot stall requests."""
+        if not isfinite(value):
+            raise ValueError("backoff_factor must be finite")
+        return value
+
+
+class AuthConfig(BaseModel):
+    """Collect an authentication handler and optional token-refresh settings."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    auth: Any | None = Field(
+        default=None,
+        repr=False,
+        description="Authentication object compatible with HTTPX or AuthBase",
+    )
+    refresh_token: str | None = Field(
+        default=None,
+        repr=False,
+        description="Refresh token retained for a caller-provided refresh callback",
+    )
+    refresh_callback: Callable[[], str] | None = Field(
+        default=None,
+        repr=False,
+        description="Synchronous callback that returns a replacement bearer or API key",
+    )

std/http/py.typed

@@ -0,0 +1 @@
+