buda-client 0.1.0__py3-none-any.whl

buda/__init__.py

@@ -0,0 +1,22 @@
+from importlib.metadata import version
+
+from buda.core.providers import DotEnvCredentials, EnvCredentials, StaticCredentials
+from buda.core.settings import BudaSettings
+from buda.rest.client.async_ import AsyncBudaClient
+from buda.rest.client.sync_ import BudaClient
+from buda.rest.models.orders import OrderCreate
+from buda.socket import BudaWebSocketClient, Channel
+
+__version__ = version("buda-client")
+
+__all__ = (
+    "AsyncBudaClient",
+    "BudaClient",
+    "BudaSettings",
+    "BudaWebSocketClient",
+    "Channel",
+    "DotEnvCredentials",
+    "EnvCredentials",
+    "OrderCreate",
+    "StaticCredentials",
+)

buda/core/auth.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import base64
+import hmac
+import time
+from typing import TYPE_CHECKING
+
+import httpx
+from httpx import Request
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+    from httpx import Response
+
+
+class BudaAuth(httpx.Auth):
+    """Attach Buda HMAC authentication to the Request object."""
+
+    __slots__ = (
+        "api_key",
+        "api_secret",
+    )
+
+    def __init__(self, api_key: str, api_secret: str):
+        self.api_key = api_key
+        self.api_secret = api_secret
+
+    def get_nonce(self) -> str:
+        """Generate a nonce (timestamp in microseconds)"""
+        return str(int(time.time() * 1e6))
+
+    def sign(self, request: httpx.Request, nonce: str) -> str:
+        """Create the HMAC signature for the request."""
+        components = [request.method, request.url.path]
+
+        if request.content:
+            body = base64.b64encode(request.content).decode()
+            components.append(body)
+        components.append(nonce)
+        message = " ".join(components)
+
+        hash = hmac.new(key=self.api_secret.encode(), msg=message.encode(), digestmod="sha384")
+
+        return hash.hexdigest()
+
+    def auth_flow(self, request: Request) -> Generator[Request, Response]:
+        nonce = self.get_nonce()
+        signature = self.sign(request, nonce)
+
+        request.headers["X-SBTC-APIKEY"] = self.api_key
+        request.headers["X-SBTC-SIGNATURE"] = signature
+        request.headers["X-SBTC-NONCE"] = nonce
+
+        yield request

buda/core/limiter.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import threading
+import time
+from collections import deque
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from buda.core.settings import BudaSettings
+
+logger = logging.getLogger("buda.limiter")
+
+
+class SyncRateLimiter:
+    """Proactive sliding-window rate limiter for synchronous requests.
+
+    Tracks per-second (shared) and per-minute (auth vs unauth) request
+    timestamps and sleeps when the next request would exceed limits.
+
+    Each ``BudaClient`` instance owns its own limiter, since Buda rate
+    limits are scoped per IP (unauthenticated) and per API key (authenticated).
+    """
+
+    __slots__ = (
+        "_enabled",
+        "_lock",
+        "_per_minute_auth",
+        "_per_minute_auth_limit",
+        "_per_minute_unauth",
+        "_per_minute_unauth_limit",
+        "_per_second",
+        "_per_second_limit",
+    )
+
+    def __init__(self, settings: BudaSettings) -> None:
+        self._enabled = settings.rate_limit_enabled
+        self._per_second_limit = settings.rate_limit_per_second
+        self._per_minute_auth_limit = settings.rate_limit_auth_per_minute
+        self._per_minute_unauth_limit = settings.rate_limit_unauth_per_minute
+
+        self._per_second: deque[float] = deque()
+        self._per_minute_auth: deque[float] = deque()
+        self._per_minute_unauth: deque[float] = deque()
+        self._lock = threading.Lock()
+
+    def _prune(self, window: deque[float], cutoff: float) -> None:
+        while window and window[0] <= cutoff:
+            window.popleft()
+
+    def acquire(self, *, authenticated: bool) -> None:
+        if not self._enabled:
+            return
+
+        with self._lock:
+            while True:
+                now = time.monotonic()
+
+                # Prune expired timestamps
+                self._prune(self._per_second, now - 1.0)
+                if authenticated:
+                    self._prune(self._per_minute_auth, now - 60.0)
+                else:
+                    self._prune(self._per_minute_unauth, now - 60.0)
+
+                # Calculate how long we need to wait (if at all)
+                wait = 0.0
+
+                if len(self._per_second) >= self._per_second_limit:
+                    wait = max(wait, self._per_second[0] + 1.0 - now)
+
+                if authenticated:
+                    if len(self._per_minute_auth) >= self._per_minute_auth_limit:
+                        wait = max(wait, self._per_minute_auth[0] + 60.0 - now)
+                else:
+                    if len(self._per_minute_unauth) >= self._per_minute_unauth_limit:
+                        wait = max(wait, self._per_minute_unauth[0] + 60.0 - now)
+
+                if wait > 0:
+                    logger.warning(
+                        "Rate limit approaching — sleeping %.2fs before request (authenticated=%s)",
+                        wait,
+                        authenticated,
+                    )
+                    # Release lock while sleeping so other threads aren't blocked
+                    self._lock.release()
+                    try:
+                        time.sleep(wait)
+                    finally:
+                        self._lock.acquire()
+                    continue  # Re-check after sleeping
+
+                # Record the request timestamp
+                self._per_second.append(now)
+                if authenticated:
+                    self._per_minute_auth.append(now)
+                else:
+                    self._per_minute_unauth.append(now)
+                return
+
+
+class AsyncRateLimiter:
+    """Proactive sliding-window rate limiter for asynchronous requests.
+
+    Same logic as :class:`SyncRateLimiter` but uses ``asyncio.Lock`` and
+    ``asyncio.sleep``.
+    """
+
+    __slots__ = (
+        "_enabled",
+        "_lock",
+        "_per_minute_auth",
+        "_per_minute_auth_limit",
+        "_per_minute_unauth",
+        "_per_minute_unauth_limit",
+        "_per_second",
+        "_per_second_limit",
+    )
+
+    def __init__(self, settings: BudaSettings) -> None:
+        self._enabled = settings.rate_limit_enabled
+        self._per_second_limit = settings.rate_limit_per_second
+        self._per_minute_auth_limit = settings.rate_limit_auth_per_minute
+        self._per_minute_unauth_limit = settings.rate_limit_unauth_per_minute
+
+        self._per_second: deque[float] = deque()
+        self._per_minute_auth: deque[float] = deque()
+        self._per_minute_unauth: deque[float] = deque()
+        self._lock = asyncio.Lock()
+
+    def _prune(self, window: deque[float], cutoff: float) -> None:
+        while window and window[0] <= cutoff:
+            window.popleft()
+
+    async def acquire(self, *, authenticated: bool) -> None:
+        if not self._enabled:
+            return
+
+        async with self._lock:
+            while True:
+                now = time.monotonic()
+
+                self._prune(self._per_second, now - 1.0)
+                if authenticated:
+                    self._prune(self._per_minute_auth, now - 60.0)
+                else:
+                    self._prune(self._per_minute_unauth, now - 60.0)
+
+                wait = 0.0
+
+                if len(self._per_second) >= self._per_second_limit:
+                    wait = max(wait, self._per_second[0] + 1.0 - now)
+
+                if authenticated:
+                    if len(self._per_minute_auth) >= self._per_minute_auth_limit:
+                        wait = max(wait, self._per_minute_auth[0] + 60.0 - now)
+                else:
+                    if len(self._per_minute_unauth) >= self._per_minute_unauth_limit:
+                        wait = max(wait, self._per_minute_unauth[0] + 60.0 - now)
+
+                if wait > 0:
+                    logger.warning(
+                        "Rate limit approaching — sleeping %.2fs before request (authenticated=%s)",
+                        wait,
+                        authenticated,
+                    )
+                    await asyncio.sleep(wait)
+                    continue
+
+                self._per_second.append(now)
+                if authenticated:
+                    self._per_minute_auth.append(now)
+                else:
+                    self._per_minute_unauth.append(now)
+                return

buda/core/providers.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import Field, SecretStr, model_serializer
+from pydantic_settings import BaseSettings, PydanticBaseSettingsSource, SettingsConfigDict
+
+
+class BudaCredentials(BaseSettings):
+    """Buda API credentials."""
+
+    api_key: SecretStr = Field(..., validation_alias="buda_api_key")
+    api_secret: SecretStr = Field(..., validation_alias="buda_api_secret")
+
+    @model_serializer(mode="plain", return_type=dict[str, str])
+    def serialize(self) -> dict[str, str]:
+        return {
+            "api_key": self.api_key.get_secret_value(),
+            "api_secret": self.api_secret.get_secret_value(),
+        }
+
+
+class StaticCredentials(BudaCredentials):
+    """Provider that uses static credentials."""
+
+    def __init__(self, *, api_key: str, api_secret: str) -> None:
+        super().__init__(buda_api_key=api_key, buda_api_secret=api_secret)  # type: ignore
+
+
+class EnvCredentials(BudaCredentials):
+    """Provider that loads credentials from environment variables."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="BUDA_",
+    )
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+
+
+class DotEnvCredentials(BudaCredentials):
+    """Provider that loads credentials from a .env file."""
+
+    model_config = SettingsConfigDict(env_file=".env")
+
+    def __init__(self, env_file: str = ".env", **kwargs: Any) -> None:
+        super().__init__(_env_file=env_file, **kwargs)  # type: ignore
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        return (dotenv_settings,)

buda/core/retry.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import functools
+import logging
+from typing import TYPE_CHECKING, Any
+
+from httpx import HTTPStatusError
+from tenacity import (
+    AsyncRetrying,
+    RetryCallState,
+    Retrying,
+    before_sleep_log,
+    retry_if_exception,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from tenacity.wait import WaitBaseT
+
+    from buda.core.settings import BudaSettings
+
+logger = logging.getLogger("buda.retry")
+
+RETRYABLE_STATUS_CODES: frozenset[int] = frozenset({429, 500, 503})
+
+
+def is_retryable_error(exc: BaseException) -> bool:
+    """Return ``True`` if *exc* is an HTTP error with a retryable status code."""
+    return isinstance(exc, HTTPStatusError) and exc.response.status_code in RETRYABLE_STATUS_CODES
+
+
+class _RetryAfterWait:
+    """Tenacity wait strategy that honours the ``Retry-After`` header.
+
+    If the last exception is a 429 with a ``Retry-After`` header the wait
+    time will be *at least* the value specified by the server.  Otherwise
+    it falls back to zero so a chained exponential strategy takes over.
+    """
+
+    def __call__(self, retry_state: RetryCallState) -> float:
+        exc = retry_state.outcome and retry_state.outcome.exception()
+        if isinstance(exc, HTTPStatusError) and exc.response.status_code == 429:
+            retry_after = exc.response.headers.get("Retry-After")
+            if retry_after is not None:
+                try:
+                    wait = float(retry_after)
+                    logger.info(
+                        "Server returned Retry-After: %.2fs — will wait at least that long",
+                        wait,
+                    )
+                    return wait
+                except (ValueError, OverflowError):
+                    pass
+        return 0.0
+
+
+def _build_wait(settings: BudaSettings) -> WaitBaseT:
+    """Build a combined wait strategy: Retry-After header OR exponential backoff."""
+    retry_after: Any = _RetryAfterWait()
+    exponential: Any = wait_exponential(
+        min=settings.retry_min_wait,
+        max=settings.retry_max_wait,
+        exp_base=settings.retry_exponential_base,
+    )
+    # For each attempt pick the larger of [Retry-After header, exponential backoff].
+    return retry_after + exponential
+
+
+def sync_retry_on_error(fn: Callable[..., Any]) -> Callable[..., Any]:
+    """Decorator for synchronous methods that retries on 429 / 500 / 503.
+
+    Reads retry configuration from ``self._settings`` at call time, so each
+    client instance can have its own retry policy.
+    """
+
+    @functools.wraps(fn)
+    def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+        if not self._settings.retry_enabled:
+            return fn(self, *args, **kwargs)
+        retrying = Retrying(
+            retry=retry_if_exception(is_retryable_error),
+            stop=stop_after_attempt(self._settings.retry_max_attempts),
+            wait=_build_wait(self._settings),
+            before_sleep=before_sleep_log(logger, logging.WARNING),
+            reraise=True,
+        )
+        return retrying(fn, self, *args, **kwargs)
+
+    return wrapper
+
+
+def async_retry_on_error(fn: Callable[..., Any]) -> Callable[..., Any]:
+    """Decorator for async methods that retries on 429 / 500 / 503.
+
+    Same semantics as :func:`sync_retry_on_error` but for coroutines.
+    """
+
+    @functools.wraps(fn)
+    async def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+        if not self._settings.retry_enabled:
+            return await fn(self, *args, **kwargs)
+        retrying = AsyncRetrying(
+            retry=retry_if_exception(is_retryable_error),
+            stop=stop_after_attempt(self._settings.retry_max_attempts),
+            wait=_build_wait(self._settings),
+            before_sleep=before_sleep_log(logger, logging.WARNING),
+            reraise=True,
+        )
+        return await retrying(fn, self, *args, **kwargs)
+
+    return wrapper

buda/core/settings.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import BeforeValidator, Field, HttpUrl, WebsocketUrl
+from pydantic.dataclasses import dataclass
+
+BaseUrl = Annotated[str, BeforeValidator(lambda v: HttpUrl(v).encoded_string())]
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class BudaSettings:
+    """Settings for Buda API clients."""
+
+    # REST API Settings
+    base_url: BaseUrl = Field(
+        default="https://www.buda.com/api/v2",
+        description="Base URL for the Buda API",
+    )
+    timeout: float | int = Field(
+        default=10.0,
+        union_mode="left_to_right",
+        description="Timeout for API requests in seconds",
+    )
+
+    # REST API - Retry Settings (tenacity)
+    retry_enabled: bool = Field(
+        default=True,
+        description="Enable automatic retry for 429, 500, and 503 HTTP errors",
+    )
+    retry_max_attempts: int = Field(
+        default=3,
+        description="Maximum number of retry attempts",
+    )
+    retry_min_wait: float = Field(
+        default=1.0,
+        description="Minimum wait time between retries in seconds",
+    )
+    retry_max_wait: float = Field(
+        default=30.0,
+        description="Maximum wait time between retries in seconds",
+    )
+    retry_exponential_base: float = Field(
+        default=2.0,
+        description="Base for exponential backoff between retries",
+    )
+
+    # REST API - Rate Limit Settings
+    rate_limit_enabled: bool = Field(
+        default=True,
+        description="Enable proactive rate limiting",
+    )
+    rate_limit_per_second: int = Field(
+        default=20,
+        description="Maximum requests per second (shared across auth/unauth)",
+    )
+    rate_limit_auth_per_minute: int = Field(
+        default=375,
+        description="Maximum authenticated requests per minute (per API key)",
+    )
+    rate_limit_unauth_per_minute: int = Field(
+        default=120,
+        description="Maximum unauthenticated requests per minute (per IP)",
+    )
+
+    # WebSocket API Settings
+    base_uri: WebsocketUrl = Field(
+        default=WebsocketUrl("wss://realtime.buda.com"),
+        description="Base URI for the Buda WebSocket API",
+    )
+    open_timeout: float | None = Field(
+        default=10.0,
+        description="Timeout for opening WebSocket connections in seconds",
+    )
+    ping_interval: float | None = Field(
+        default=10.0,
+        description="Interval for sending WebSocket pings in seconds",
+    )
+    ping_timeout: float | None = Field(
+        default=20.0,
+        description="Timeout for WebSocket pings in seconds",
+    )
+    close_timeout: float | None = Field(
+        default=10.0,
+        description="Timeout for closing WebSocket connections in seconds",
+    )
+
+    # Common Settings
+    user_agent: str = Field(
+        default="python-buda-client/0.1.0",
+        description="User agent for the Buda API client",
+    )
+
+    @property
+    def headers(self) -> dict[str, str]:
+        """Default headers for API requests."""
+        return {
+            "User-Agent": self.user_agent,
+        }