smooai-fetch 2.1.2__tar.gz

smooai_fetch-2.1.2/.gitignore

@@ -0,0 +1,57 @@
+lib-cov
+*.seed
+*.log
+*.csv
+*.dat
+*.out
+*.pid
+*.gz
+*.swp
+
+pids
+logs
+results
+tmp
+
+# Build
+public/css/main.css
+
+# Coverage reports
+coverage
+
+# API keys and secrets
+.env
+
+# Dependency directory
+node_modules
+bower_components
+
+# Editors
+.idea
+*.iml
+
+# OS metadata
+.DS_Store
+Thumbs.db
+
+# Ignore built ts files
+dist/**/*
+
+# ignore yarn.lock
+yarn.lock
+
+# ignore package-lock.json
+package-lock.json
+
+.envrc
+# Rust build artifacts
+rust/fetch/target/
+
+# Python build artifacts
+python/dist/
+python/.venv/
+python/uv.lock
+__pycache__/
+*.pyc
+
+# Go

smooai_fetch-2.1.2/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: smooai-fetch
+Version: 2.1.2
+Summary: A resilient HTTP fetch client with retries, timeouts, rate limiting, and circuit breaking.
+Project-URL: Homepage, https://github.com/SmooAI/fetch
+Project-URL: Repository, https://github.com/SmooAI/fetch
+Project-URL: Issues, https://github.com/SmooAI/fetch/issues
+Author-email: SmooAI <brent@smooai.com>
+License: MIT
+Keywords: circuit-breaker,fetch,http,retry,smooai
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0

smooai_fetch-2.1.2/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "smooai-fetch"
+version = "2.1.2"
+description = "A resilient HTTP fetch client with retries, timeouts, rate limiting, and circuit breaking."
+# readme = "README.md"
+authors = [{ name = "SmooAI", email = "brent@smooai.com" }]
+license = { text = "MIT" }
+requires-python = ">=3.12"
+dependencies = ["httpx>=0.27.0", "pydantic>=2.0.0"]
+classifiers = [
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+keywords = ["fetch", "http", "retry", "circuit-breaker", "smooai"]
+
+[project.urls]
+Homepage = "https://github.com/SmooAI/fetch"
+Repository = "https://github.com/SmooAI/fetch"
+Issues = "https://github.com/SmooAI/fetch/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/smooai_fetch"]
+
+[dependency-groups]
+dev = ["pytest>=8.0.0", "pytest-asyncio>=0.24.0", "respx>=0.22.0", "ruff>=0.11.0", "basedpyright>=1.0.0", "poethepoet>=0.29.0"]
+
+[tool.poe.tasks]
+lint = "ruff check src/ tests/"
+"lint:fix" = "ruff check --fix src/ tests/"
+format = "ruff format src/ tests/"
+"format:check" = "ruff format --check src/ tests/"
+typecheck = "basedpyright src/"
+test = "uv run pytest tests/ -v"
+build = "uv build --wheel --sdist"
+"install-dev" = "uv sync --group dev"
+
+[tool.poe.tasks.publish]
+sequence = [{ cmd = "uv build --wheel --sdist" }, { cmd = "uv publish" }]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+ignore = ["UP046", "UP047"] # Keep TypeVar/Generic style for broader compatibility
+
+[tool.basedpyright]
+pythonVersion = "3.12"
+typeCheckingMode = "standard"

smooai_fetch-2.1.2/src/smooai_fetch/__init__.py

@@ -0,0 +1,91 @@
+"""Smoo AI Fetch Client - Python SDK.
+
+A resilient HTTP fetch client with retries, timeouts, rate limiting,
+and circuit breaking.
+"""
+
+__version__ = "2.1.2"
+
+# Core client
+# Builder
+from smooai_fetch._builder import FetchBuilder
+
+# Circuit breaker
+from smooai_fetch._circuit_breaker import CircuitBreaker
+from smooai_fetch._client import fetch
+
+# Defaults
+from smooai_fetch._defaults import (
+    DEFAULT_RETRY_OPTIONS,
+    DEFAULT_TIMEOUT_MS,
+    DEFAULT_TIMEOUT_OPTIONS,
+)
+
+# Errors
+from smooai_fetch._errors import (
+    CircuitBreakerError,
+    FetchError,
+    HTTPResponseError,
+    RateLimitError,
+    RetryError,
+    SchemaValidationError,
+)
+from smooai_fetch._errors import TimeoutError as TimeoutError
+
+# Rate limiter
+from smooai_fetch._rate_limit import SlidingWindowRateLimiter
+
+# Response
+from smooai_fetch._response import FetchResponse
+
+# Retry utilities
+from smooai_fetch._retry import calculate_backoff, is_retryable
+
+# Types
+from smooai_fetch._types import (
+    CircuitBreakerOptions,
+    FetchContainerOptions,
+    FetchOptions,
+    LifecycleHooks,
+    PostResponseErrorHook,
+    PostResponseSuccessHook,
+    PreRequestHook,
+    RateLimitOptions,
+    RetryOptions,
+    TimeoutOptions,
+)
+
+__all__ = [
+    # Core
+    "fetch",
+    "FetchBuilder",
+    "FetchResponse",
+    # Types
+    "CircuitBreakerOptions",
+    "FetchContainerOptions",
+    "FetchOptions",
+    "LifecycleHooks",
+    "PostResponseErrorHook",
+    "PostResponseSuccessHook",
+    "PreRequestHook",
+    "RateLimitOptions",
+    "RetryOptions",
+    "TimeoutOptions",
+    # Defaults
+    "DEFAULT_RETRY_OPTIONS",
+    "DEFAULT_TIMEOUT_MS",
+    "DEFAULT_TIMEOUT_OPTIONS",
+    # Errors
+    "CircuitBreakerError",
+    "FetchError",
+    "HTTPResponseError",
+    "RateLimitError",
+    "RetryError",
+    "SchemaValidationError",
+    "TimeoutError",
+    # Utilities
+    "calculate_backoff",
+    "is_retryable",
+    "SlidingWindowRateLimiter",
+    "CircuitBreaker",
+]

smooai_fetch-2.1.2/src/smooai_fetch/_builder.py

@@ -0,0 +1,230 @@
+"""Fluent builder for configuring fetch instances."""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+from pydantic import BaseModel
+
+from smooai_fetch._client import fetch as _fetch
+from smooai_fetch._defaults import DEFAULT_RETRY_OPTIONS
+from smooai_fetch._response import FetchResponse
+from smooai_fetch._types import (
+    CircuitBreakerOptions,
+    FetchContainerOptions,
+    FetchOptions,
+    LifecycleHooks,
+    PostResponseErrorHook,
+    PostResponseSuccessHook,
+    PreRequestHook,
+    RateLimitOptions,
+    RetryOptions,
+    TimeoutOptions,
+)
+
+T = TypeVar("T")
+
+
+class FetchBuilder:
+    """Builder class for creating configured fetch instances with retry,
+    rate limiting, and circuit breaking.
+
+    Provides a fluent interface for configuring fetch options.
+
+    Example::
+
+        builder = FetchBuilder()
+        builder = (
+            builder
+            .with_retry(RetryOptions(attempts=3))
+            .with_timeout(5000)
+            .with_rate_limit(RateLimitOptions(max_requests=10, window_ms=60000))
+            .with_headers({"Authorization": "Bearer token"})
+        )
+        response = await builder.fetch("https://api.example.com/data")
+    """
+
+    def __init__(self) -> None:
+        self._retry: RetryOptions | None = None
+        self._timeout: TimeoutOptions | None = None
+        self._rate_limit: RateLimitOptions | None = None
+        self._circuit_breaker: CircuitBreakerOptions | None = None
+        self._schema: type[BaseModel] | None = None
+        self._headers: dict[str, str] = {}
+        self._hooks: LifecycleHooks = LifecycleHooks()
+
+    def with_retry(self, options: RetryOptions | None = None) -> FetchBuilder:
+        """Configure retry behavior.
+
+        Args:
+            options: Retry configuration. Defaults to DEFAULT_RETRY_OPTIONS if None.
+
+        Returns:
+            The builder instance for method chaining.
+        """
+        self._retry = options if options is not None else DEFAULT_RETRY_OPTIONS
+        return self
+
+    def with_timeout(self, timeout_ms: float) -> FetchBuilder:
+        """Set the request timeout.
+
+        Args:
+            timeout_ms: Timeout duration in milliseconds.
+
+        Returns:
+            The builder instance for method chaining.
+        """
+        self._timeout = TimeoutOptions(timeout_ms=timeout_ms)
+        return self
+
+    def with_rate_limit(self, options: RateLimitOptions) -> FetchBuilder:
+        """Configure rate limiting.
+
+        Args:
+            options: Rate limit configuration.
+
+        Returns:
+            The builder instance for method chaining.
+        """
+        self._rate_limit = options
+        return self
+
+    def with_circuit_breaker(self, options: CircuitBreakerOptions) -> FetchBuilder:
+        """Configure circuit breaker behavior.
+
+        Args:
+            options: Circuit breaker configuration.
+
+        Returns:
+            The builder instance for method chaining.
+        """
+        self._circuit_breaker = options
+        return self
+
+    def with_schema(self, schema: type[BaseModel]) -> FetchBuilder:
+        """Set a Pydantic model for response validation.
+
+        Args:
+            schema: The Pydantic model class to validate against.
+
+        Returns:
+            The builder instance for method chaining.
+        """
+        self._schema = schema
+        return self
+
+    def with_headers(self, headers: dict[str, str]) -> FetchBuilder:
+        """Set default headers for all requests.
+
+        Args:
+            headers: Dictionary of header name-value pairs.
+
+        Returns:
+            The builder instance for method chaining.
+        """
+        self._headers.update(headers)
+        return self
+
+    def with_auth(self, token: str, scheme: str = "Bearer") -> FetchBuilder:
+        """Set an authorization header.
+
+        Args:
+            token: The authentication token.
+            scheme: The auth scheme (default: "Bearer").
+
+        Returns:
+            The builder instance for method chaining.
+        """
+        self._headers["Authorization"] = f"{scheme} {token}"
+        return self
+
+    def with_pre_request_hook(self, hook: PreRequestHook) -> FetchBuilder:
+        """Set a pre-request hook.
+
+        Args:
+            hook: Function called before each request.
+
+        Returns:
+            The builder instance for method chaining.
+        """
+        self._hooks.pre_request = hook
+        return self
+
+    def with_post_response_success_hook(self, hook: PostResponseSuccessHook) -> FetchBuilder:
+        """Set a post-response success hook.
+
+        Args:
+            hook: Function called after a successful response.
+
+        Returns:
+            The builder instance for method chaining.
+        """
+        self._hooks.post_response_success = hook
+        return self
+
+    def with_post_response_error_hook(self, hook: PostResponseErrorHook) -> FetchBuilder:
+        """Set a post-response error hook.
+
+        Args:
+            hook: Function called after a failed response.
+
+        Returns:
+            The builder instance for method chaining.
+        """
+        self._hooks.post_response_error = hook
+        return self
+
+    def build(self) -> FetchOptions:
+        """Build the FetchOptions from the current configuration.
+
+        Returns:
+            A FetchOptions instance with all configured settings.
+        """
+        container_options: FetchContainerOptions | None = None
+        if self._rate_limit or self._circuit_breaker:
+            container_options = FetchContainerOptions(
+                rate_limit=self._rate_limit,
+                circuit_breaker=self._circuit_breaker,
+            )
+
+        return FetchOptions(
+            headers=self._headers if self._headers else None,
+            retry=self._retry,
+            timeout=self._timeout,
+            schema=self._schema,
+            hooks=self._hooks,
+            container_options=container_options,
+        )
+
+    async def fetch(
+        self,
+        url: str,
+        method: str = "GET",
+        headers: dict[str, str] | None = None,
+        body: Any = None,
+    ) -> FetchResponse[Any]:
+        """Execute a request using the built configuration.
+
+        Args:
+            url: The URL to request.
+            method: HTTP method (default: "GET").
+            headers: Additional headers for this specific request.
+            body: Request body.
+
+        Returns:
+            A FetchResponse containing the parsed response data.
+        """
+        opts = self.build()
+        opts.method = method
+
+        # Merge per-request headers with builder headers
+        merged_headers = dict(self._headers) if self._headers else {}
+        if headers:
+            merged_headers.update(headers)
+        if merged_headers:
+            opts.headers = merged_headers
+
+        if body is not None:
+            opts.body = body
+
+        return await _fetch(url, opts)

smooai_fetch-2.1.2/src/smooai_fetch/_circuit_breaker.py

@@ -0,0 +1,129 @@
+"""Circuit breaker implementation for the smooai-fetch client.
+
+Implements a simple async-compatible circuit breaker without relying on
+pybreaker's async support (which requires tornado).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Awaitable, Callable
+from enum import Enum
+from typing import TypeVar
+
+from smooai_fetch._errors import CircuitBreakerError
+from smooai_fetch._types import CircuitBreakerOptions
+
+T = TypeVar("T")
+
+
+class CircuitState(Enum):
+    """Possible states of the circuit breaker."""
+
+    CLOSED = "closed"
+    OPEN = "open"
+    HALF_OPEN = "half-open"
+
+
+class CircuitBreaker:
+    """An async-compatible circuit breaker.
+
+    State transitions:
+    - CLOSED: Normal operation. Failures are counted.
+    - OPEN: Requests are rejected immediately. After timeout, transitions to HALF_OPEN.
+    - HALF_OPEN: A limited number of requests are allowed through. If they succeed
+      (reaching success_threshold), transitions to CLOSED. If one fails, transitions
+      back to OPEN.
+    """
+
+    def __init__(self, options: CircuitBreakerOptions) -> None:
+        self._failure_threshold = options.failure_threshold
+        self._success_threshold = options.success_threshold
+        self._timeout = options.timeout  # seconds
+
+        self._state = CircuitState.CLOSED
+        self._failure_count = 0
+        self._success_count = 0
+        self._last_failure_time: float | None = None
+        self._lock = asyncio.Lock()
+
+    @property
+    def state(self) -> str:
+        """Current state of the circuit breaker as a string."""
+        # Check if we should transition from OPEN to HALF_OPEN
+        if self._state == CircuitState.OPEN and self._last_failure_time is not None:
+            elapsed = time.monotonic() - self._last_failure_time
+            if elapsed >= self._timeout:
+                return CircuitState.HALF_OPEN.value
+        return self._state.value
+
+    async def call(self, func: Callable[..., Awaitable[T]]) -> T:
+        """Execute an async function through the circuit breaker.
+
+        Args:
+            func: The async callable to execute.
+
+        Returns:
+            The result of the function.
+
+        Raises:
+            CircuitBreakerError: If the circuit is open and timeout has not elapsed.
+        """
+        async with self._lock:
+            current_state = self._get_state()
+
+            if current_state == CircuitState.OPEN:
+                raise CircuitBreakerError("Circuit breaker is open")
+
+            if current_state == CircuitState.HALF_OPEN:
+                # Allow the request through, but track carefully
+                pass
+
+        # Execute the function outside the lock
+        try:
+            result = await func()
+        except Exception:
+            async with self._lock:
+                self._record_failure()
+            raise
+
+        async with self._lock:
+            self._record_success()
+
+        return result
+
+    def _get_state(self) -> CircuitState:
+        """Get the current state, potentially transitioning OPEN -> HALF_OPEN."""
+        if self._state == CircuitState.OPEN and self._last_failure_time is not None:
+            elapsed = time.monotonic() - self._last_failure_time
+            if elapsed >= self._timeout:
+                self._state = CircuitState.HALF_OPEN
+                self._success_count = 0
+                return CircuitState.HALF_OPEN
+        return self._state
+
+    def _record_success(self) -> None:
+        """Record a successful call."""
+        if self._state == CircuitState.HALF_OPEN:
+            self._success_count += 1
+            if self._success_count >= self._success_threshold:
+                self._state = CircuitState.CLOSED
+                self._failure_count = 0
+                self._success_count = 0
+        elif self._state == CircuitState.CLOSED:
+            # Reset failure count on success in closed state
+            self._failure_count = 0
+
+    def _record_failure(self) -> None:
+        """Record a failed call."""
+        if self._state == CircuitState.HALF_OPEN:
+            # Any failure in half-open goes back to open
+            self._state = CircuitState.OPEN
+            self._last_failure_time = time.monotonic()
+            self._success_count = 0
+        elif self._state == CircuitState.CLOSED:
+            self._failure_count += 1
+            if self._failure_count >= self._failure_threshold:
+                self._state = CircuitState.OPEN
+                self._last_failure_time = time.monotonic()