stonepy 0.1.0__py3-none-any.whl

stonepy/__init__.py

@@ -0,0 +1,27 @@
+from stonepy._core.config import ClientConfig
+from stonepy._core.errors import (
+    AuthenticationError,
+    OrderRejectedError,
+    RateLimitError,
+    ResponseParseError,
+    StoneXAPIError,
+    StoneXError,
+    TransportError,
+)
+from stonepy.client import AsyncStoneXClient, StoneXClient
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncStoneXClient",
+    "AuthenticationError",
+    "ClientConfig",
+    "OrderRejectedError",
+    "RateLimitError",
+    "ResponseParseError",
+    "StoneXAPIError",
+    "StoneXClient",
+    "StoneXError",
+    "TransportError",
+    "__version__",
+]

stonepy/_core/__init__.py

@@ -0,0 +1 @@
+

stonepy/_core/clock.py

@@ -0,0 +1,49 @@
+"""Clock abstraction so timing logic is testable with a fake clock."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Protocol, runtime_checkable
+
+
+class Clock(Protocol):
+    def now(self) -> float: ...
+    def sleep(self, seconds: float) -> None: ...
+
+
+@runtime_checkable
+class AsyncClock(Clock, Protocol):
+    async def asleep(self, seconds: float) -> None: ...
+
+
+class SystemClock:
+    def now(self) -> float:
+        return time.monotonic()
+
+    def sleep(self, seconds: float) -> None:
+        if seconds > 0:
+            time.sleep(seconds)
+
+    async def asleep(self, seconds: float) -> None:
+        if seconds > 0:
+            await asyncio.sleep(seconds)
+
+
+class FakeClock:
+    def __init__(self) -> None:
+        self._t = 0.0
+
+    def now(self) -> float:
+        return self._t
+
+    def sleep(self, seconds: float) -> None:
+        self._t += max(0.0, seconds)
+
+    async def asleep(self, seconds: float) -> None:
+        self.sleep(seconds)
+
+    def advance(self, seconds: float) -> None:
+        if seconds < 0:
+            raise ValueError("seconds must be non-negative")
+        self._t += seconds

stonepy/_core/codec.py

@@ -0,0 +1,96 @@
+"""Decimal-safe JSON and WCF (`/Date(ms)/`) date handling."""
+
+from __future__ import annotations
+
+import json
+import re
+from datetime import UTC, datetime, timedelta
+from decimal import Decimal
+from typing import Annotated, Any, NoReturn, TypeAlias
+
+import simplejson
+from pydantic import BeforeValidator, PlainSerializer
+
+WCF_MINVALUE_MS = -62135596800000
+_WCF_RE = re.compile(r"\\?/Date\((-?\d+)(?:[+-]\d{4})?\)\\?/")
+_UTC_EPOCH = datetime(1970, 1, 1, tzinfo=UTC)
+_MS_PER_DAY = 86_400_000
+_MS_PER_SECOND = 1_000
+
+
+def _ensure_timezone_aware(value: datetime) -> datetime:
+    if value.utcoffset() is None:
+        raise ValueError("datetime must be timezone-aware")
+    return value
+
+
+def parse_wcf_date(value: Any) -> datetime | None:
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        return _ensure_timezone_aware(value)
+    if isinstance(value, bool):
+        raise ValueError(f"not a WCF date: {value!r}")
+    if isinstance(value, int):
+        ms = value
+    elif isinstance(value, str):
+        m = _WCF_RE.fullmatch(value)
+        if not m:
+            raise ValueError(f"not a WCF date: {value!r}")
+        ms = int(m.group(1))
+    else:
+        raise ValueError(f"not a WCF date: {value!r}")
+    if ms == WCF_MINVALUE_MS:
+        return None
+    try:
+        return _UTC_EPOCH + timedelta(milliseconds=ms)
+    except OverflowError as exc:
+        raise ValueError(f"WCF date out of range: {value!r}") from exc
+
+
+def format_wcf_date(value: datetime | None) -> str | None:
+    if value is None:
+        return None
+    aware_value = _ensure_timezone_aware(value)
+    delta = aware_value.astimezone(UTC) - _UTC_EPOCH
+    ms = (
+        delta.days * _MS_PER_DAY
+        + delta.seconds * _MS_PER_SECOND
+        + delta.microseconds // _MS_PER_SECOND
+    )
+    return f"/Date({ms})/"
+
+
+StoneXDateTime: TypeAlias = Annotated[
+    datetime | None,
+    BeforeValidator(parse_wcf_date),
+    PlainSerializer(format_wcf_date, when_used="always"),
+]
+
+
+def _reject_nonfinite_decimals(value: Any) -> None:
+    if isinstance(value, Decimal):
+        if not value.is_finite():
+            raise ValueError("non-finite Decimal values are not valid JSON")
+    elif isinstance(value, dict):
+        for key, item in value.items():
+            _reject_nonfinite_decimals(key)
+            _reject_nonfinite_decimals(item)
+    elif isinstance(value, (list, tuple)):
+        for item in value:
+            _reject_nonfinite_decimals(item)
+
+
+def _reject_json_constant(value: str) -> NoReturn:
+    raise ValueError(f"non-finite JSON constant is not allowed: {value}")
+
+
+def dumps(obj: Any) -> str:
+    _reject_nonfinite_decimals(obj)
+    return simplejson.dumps(obj, use_decimal=True, allow_nan=False, separators=(",", ":"))
+
+
+def loads(text: str | bytes) -> Any:
+    if isinstance(text, bytes):
+        text = text.decode("utf-8")
+    return json.loads(text, parse_float=Decimal, parse_constant=_reject_json_constant)

stonepy/_core/config.py

@@ -0,0 +1,118 @@
+"""Client configuration."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, fields
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any, TypeVar, cast
+
+from stonepy._core.logging import safe_repr
+from stonepy._core.status import StatusDecoder, default_status_decoder
+
+_T = TypeVar("_T")
+_FALLBACK_VERSION = "0.1.0"
+
+
+def _default_user_agent() -> str:
+    try:
+        package_version = version("stonepy")
+    except PackageNotFoundError:
+        package_version = _FALLBACK_VERSION
+    return f"stonepy/{package_version}"
+
+
+_DEFAULT_USER_AGENT = _default_user_agent()
+
+
+@dataclass
+class ClientConfig:
+    """Configuration for StoneX clients.
+
+    `base_url` is required and points at the CIAPI root. `app_key`, `username`, and
+    `password` enable automatic session refresh. Timeout, retry, rate-limit, TLS, proxy,
+    plugin, and status-decoder fields tune transport behavior. Use `from_env()` to read the
+    `STONEX_*` environment variables with optional keyword overrides.
+    """
+
+    base_url: str
+    app_key: str = ""
+    username: str = ""
+    password: str = ""
+    app_version: str = "stonepy"
+    connect_timeout: float = 10.0
+    read_timeout: float = 30.0
+    write_timeout: float = 30.0
+    pool_timeout: float = 5.0
+    max_connections: int = 20
+    verify_tls: bool = True
+    proxy: str | None = None
+    user_agent: str = _DEFAULT_USER_AGENT
+    max_retries: int = 3
+    retry_budget_seconds: float = 30.0
+    rate_limit_max: int = 500
+    rate_limit_window_seconds: float = 5.0
+    proactive_refresh_seconds: float = 1080.0
+    status_decoder: StatusDecoder | None = default_status_decoder
+    enable_plugins: bool = False
+    allow_overrides: tuple[str, ...] = ()
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> ClientConfig:
+        known_fields = {field.name for field in fields(cls)}
+        unknown_fields = set(overrides) - known_fields
+        if unknown_fields:
+            unknown = sorted(unknown_fields)[0]
+            raise TypeError(f"unexpected ClientConfig override: {unknown}")
+
+        base_url = _override(
+            overrides,
+            "base_url",
+            os.environ.get("STONEX_BASE_URL", ""),
+        )
+        if not base_url.strip():
+            raise ValueError("base_url is required: set STONEX_BASE_URL or pass base_url=...")
+
+        return cls(
+            base_url=base_url,
+            app_key=_override(overrides, "app_key", os.environ.get("STONEX_APP_KEY", "")),
+            username=_override(overrides, "username", os.environ.get("STONEX_USERNAME", "")),
+            password=_override(overrides, "password", os.environ.get("STONEX_PASSWORD", "")),
+            app_version=_override(overrides, "app_version", "stonepy"),
+            connect_timeout=_override(overrides, "connect_timeout", 10.0),
+            read_timeout=_override(overrides, "read_timeout", 30.0),
+            write_timeout=_override(overrides, "write_timeout", 30.0),
+            pool_timeout=_override(overrides, "pool_timeout", 5.0),
+            max_connections=_override(overrides, "max_connections", 20),
+            verify_tls=_override(overrides, "verify_tls", True),
+            proxy=_override(overrides, "proxy", None),
+            user_agent=_override(overrides, "user_agent", _DEFAULT_USER_AGENT),
+            max_retries=_override(overrides, "max_retries", 3),
+            retry_budget_seconds=_override(overrides, "retry_budget_seconds", 30.0),
+            rate_limit_max=_override(overrides, "rate_limit_max", 500),
+            rate_limit_window_seconds=_override(overrides, "rate_limit_window_seconds", 5.0),
+            proactive_refresh_seconds=_override(overrides, "proactive_refresh_seconds", 1080.0),
+            status_decoder=_override_nullable(
+                overrides,
+                "status_decoder",
+                default_status_decoder,
+            ),
+            enable_plugins=_override(overrides, "enable_plugins", False),
+            allow_overrides=_override(overrides, "allow_overrides", ()),
+        )
+
+    def __repr__(self) -> str:
+        return safe_repr(self)
+
+
+def _override(overrides: dict[str, Any], name: str, default: _T) -> _T:
+    value = overrides.get(name, default)
+    if value is None:
+        return default
+    return cast(_T, value)
+
+
+def _override_nullable(overrides: dict[str, Any], name: str, default: _T) -> _T | None:
+    if name in overrides:
+        return cast(_T | None, overrides[name])
+    return default

stonepy/_core/endpoint.py

@@ -0,0 +1,36 @@
+"""Endpoint metadata emitted by the generator and consumed by the pipeline."""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field
+from typing import Generic, Literal, TypeVar
+
+from pydantic import BaseModel
+
+ResponseT = TypeVar("ResponseT", bound=BaseModel)
+
+
+class AuthPolicy(enum.Enum):
+    NONE = "none"
+    SESSION = "session"
+
+
+@dataclass(frozen=True)
+class Param:
+    name: str
+    location: Literal["path", "query", "body"]
+    python_name: str
+
+
+@dataclass(frozen=True)
+class EndpointSpec(Generic[ResponseT]):
+    name: str
+    method: str
+    path: str
+    idempotent: bool
+    auth_policy: AuthPolicy
+    rate_limit_bucket: str
+    response_model: type[ResponseT]
+    request_model: type | None = None
+    params: tuple[Param, ...] = field(default_factory=tuple)

stonepy/_core/errors.py

@@ -0,0 +1,169 @@
+"""Exception hierarchy for stonepy."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+_REDACT = {"session", "password", "appkey", "authorization"}
+
+
+def _safe_headers(headers: Mapping[str, str]) -> dict[str, str]:
+    return {k: ("***" if k.lower() in _REDACT else v) for k, v in headers.items()}
+
+
+class StoneXError(Exception):
+    """Base class for all stonepy errors."""
+
+
+class StoneXAPIError(StoneXError):
+    """HTTP or API business-error response with endpoint context.
+
+    `raw_body` is retained for diagnostics and may contain sensitive response data.
+    It is intentionally omitted from `str()` and redacted from `repr()`.
+    """
+
+    def __init__(
+        self,
+        *,
+        http_status: int,
+        error_code: int | None,
+        error_message: str | None,
+        method: str,
+        path: str,
+        raw_body: bytes | None,
+        headers: Mapping[str, str],
+    ) -> None:
+        self.http_status = http_status
+        self.error_code = error_code
+        self.error_message = error_message
+        self.method = method
+        self.path = path
+        self.raw_body = raw_body
+        self.headers = dict(headers)
+        super().__init__(
+            f"{method} {path} -> HTTP {http_status} (ErrorCode={error_code}): {error_message}"
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(http_status={self.http_status}, "
+            f"error_code={self.error_code}, method={self.method!r}, "
+            f"path={self.path!r}, headers={_safe_headers(self.headers)!r})"
+        )
+
+
+class AuthenticationError(StoneXAPIError):
+    """Invalid credentials (ErrorCode 4010) or unrecoverable 401."""
+
+
+class ResponseParseError(StoneXError):
+    """Malformed or schema-invalid success response body.
+
+    `raw_body` is retained for diagnostics and may contain sensitive response data.
+    It is intentionally omitted from `str()` and redacted from `repr()`.
+    """
+
+    def __init__(
+        self,
+        *,
+        phase: str,
+        http_status: int,
+        method: str,
+        path: str,
+        raw_body: bytes,
+        message: str,
+    ) -> None:
+        self.phase = phase
+        self.http_status = http_status
+        self.method = method
+        self.path = path
+        self.raw_body = raw_body
+        super().__init__(
+            f"{method} {path} -> HTTP {http_status} response {phase} failed: {message}"
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(phase={self.phase!r}, "
+            f"http_status={self.http_status}, method={self.method!r}, path={self.path!r}, "
+            f"raw_body=<redacted {len(self.raw_body)} bytes>)"
+        )
+
+
+class RateLimitError(StoneXAPIError):
+    """Rate-limit API error with an optional parsed retry_after delay."""
+
+    def __init__(
+        self,
+        *,
+        http_status: int,
+        error_code: int | None,
+        error_message: str | None,
+        method: str,
+        path: str,
+        raw_body: bytes | None,
+        headers: Mapping[str, str],
+        retry_after: float | None = None,
+    ) -> None:
+        self.retry_after = retry_after
+        super().__init__(
+            http_status=http_status,
+            error_code=error_code,
+            error_message=error_message,
+            method=method,
+            path=path,
+            raw_body=raw_body,
+            headers=headers,
+        )
+
+
+class OrderRejectedError(StoneXError):
+    """Order business-status rejection with optional endpoint context.
+
+    `response` is retained for diagnostics and may contain sensitive response data.
+    It is intentionally omitted from `repr()`.
+    """
+
+    def __init__(
+        self,
+        *,
+        status: int,
+        status_reason: int | None,
+        reason: str | None,
+        response: object,
+        method: str | None = None,
+        path: str | None = None,
+        http_status: int | None = None,
+    ) -> None:
+        self.status = status
+        self.status_reason = status_reason
+        self.reason = reason
+        self.response = response
+        self.method = method
+        self.path = path
+        self.http_status = http_status
+        endpoint = f"{method} {path} -> HTTP {http_status}: " if method and path else ""
+        super().__init__(f"{endpoint}Order rejected: status={status} reason={reason!r}")
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(status={self.status}, "
+            f"status_reason={self.status_reason}, reason={self.reason!r}, "
+            f"method={self.method!r}, path={self.path!r}, http_status={self.http_status})"
+        )
+
+
+class TransportError(StoneXError):
+    """Network-level failure (connect/read/timeout)."""
+
+    def __init__(self, message: str, *, method: str, path: str, attempt: int) -> None:
+        self.method = method
+        self.path = path
+        self.attempt = attempt
+        super().__init__(f"{method} {path} transport failed on attempt {attempt}: {message}")
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(method={self.method!r}, path={self.path!r}, "
+            f"attempt={self.attempt})"
+        )

stonepy/_core/logging.py

@@ -0,0 +1,62 @@
+"""Logging helpers with secret redaction."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import is_dataclass
+from typing import Protocol, TypeGuard
+
+_DEFAULT_SECRET_KEYS = {"app_key", "appkey", "authorization", "password", "proxy", "session"}
+
+
+class _DataclassInstance(Protocol):
+    __dataclass_fields__: dict[str, object]
+
+
+def redact(value: str) -> str:
+    if not value:
+        return value
+    return "***"
+
+
+def safe_repr(obj: object, secret_keys: set[str] | None = None) -> str:
+    keys = _secret_keys(secret_keys)
+
+    if isinstance(obj, Mapping):
+        return repr(_redacted_mapping(obj, keys))
+
+    if _is_dataclass_instance(obj):
+        return _redacted_dataclass_repr(obj, keys)
+
+    return repr(obj)
+
+
+def _secret_keys(secret_keys: set[str] | None) -> set[str]:
+    keys = set(_DEFAULT_SECRET_KEYS)
+    if secret_keys is not None:
+        keys.update(key.lower() for key in secret_keys)
+    return keys
+
+
+def _redacted_mapping(
+    mapping: Mapping[object, object], secret_keys: set[str]
+) -> dict[object, object]:
+    return {k: _redacted_value(k, v, secret_keys) for k, v in mapping.items()}
+
+
+def _redacted_value(key: object, value: object, secret_keys: set[str]) -> object:
+    if isinstance(key, str) and key.lower() in secret_keys:
+        return "***"
+    return value
+
+
+def _is_dataclass_instance(obj: object) -> TypeGuard[_DataclassInstance]:
+    return is_dataclass(obj) and not isinstance(obj, type)
+
+
+def _redacted_dataclass_repr(obj: _DataclassInstance, secret_keys: set[str]) -> str:
+    rendered = ", ".join(
+        f"{name}={_redacted_value(name, getattr(obj, name), secret_keys)!r}"
+        for name in obj.__dataclass_fields__
+    )
+    return f"{type(obj).__qualname__}({rendered})"

stonepy/_core/models.py

@@ -0,0 +1,31 @@
+"""Base Pydantic models for requests and responses."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+from stonepy._core.codec import StoneXDateTime
+
+__all__ = [
+    "PassthroughResponseModel",
+    "RequestModel",
+    "ResponseModel",
+    "StoneXDateTime",
+    "StoneXModel",
+]
+
+
+class StoneXModel(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class RequestModel(StoneXModel):
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+
+class ResponseModel(StoneXModel):
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+
+class PassthroughResponseModel(StoneXModel):
+    model_config = ConfigDict(populate_by_name=True, extra="allow")