tradezero-sdk 1.0.0__py3-none-any.whl

tradezero/__init__.py

@@ -0,0 +1,35 @@
+"""TradeZero SDK public interface."""
+
+from tradezero.client.async_client import AsyncTradeZeroClient
+from tradezero.client.sync_client import TradeZeroClient
+from tradezero.enums import SecurityType
+from tradezero.exceptions import (
+    APIValidationError,
+    AuthenticationError,
+    ForbiddenError,
+    InsufficientFundsError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    TradeZeroAPIError,
+    TradeZeroSDKError,
+)
+from tradezero.models.orders import TradeRecord
+
+__all__ = [
+    "TradeZeroClient",
+    "AsyncTradeZeroClient",
+    "SecurityType",
+    "TradeZeroSDKError",
+    "TradeZeroAPIError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "RateLimitError",
+    "APIValidationError",
+    "NotFoundError",
+    "InsufficientFundsError",
+    "ServerError",
+    "TradeRecord",
+]
+
+__version__ = "1.0.0"

tradezero/client/__init__.py

@@ -0,0 +1,11 @@
+"""High-level client façades.
+
+Import from ``tradezero`` directly for normal usage::
+
+    from tradezero import TradeZeroClient, AsyncTradeZeroClient
+"""
+
+from tradezero.client.async_client import AsyncTradeZeroClient
+from tradezero.client.sync_client import TradeZeroClient
+
+__all__ = ["TradeZeroClient", "AsyncTradeZeroClient"]

tradezero/client/async_client.py

@@ -0,0 +1,89 @@
+"""Asynchronous top-level TradeZero client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from tradezero.config import (
+    DEFAULT_TIMEOUT,
+    base_url_from_env,
+    api_key_from_env,
+    api_secret_from_env,
+)
+from tradezero.http.async_http import AsyncHTTPClient
+from tradezero.modules.accounts import AsyncAccountsModule
+from tradezero.modules.trading import AsyncTradingModule
+from tradezero.modules.positions import AsyncPositionsModule
+from tradezero.modules.locates import AsyncLocatesModule
+
+
+class AsyncTradeZeroClient:
+    """Asynchronous entry-point for the TradeZero SDK.
+
+    Designed to be used as an async context manager::
+
+        async with AsyncTradeZeroClient(api_key="...", api_secret="...") as client:
+            positions = await client.positions.get_positions("ACC123")
+
+    Args:
+        api_key: TradeZero API key ID.  Falls back to ``TZ_API_KEY``.
+        api_secret: TradeZero API secret key.  Falls back to ``TZ_API_SECRET``.
+        base_url: Override the default base URL.  Falls back to ``TZ_BASE_URL``
+            or ``https://webapi.tradezero.com/v1/api``.
+        timeout: Per-request timeout in seconds (default: 30).
+
+    Attributes:
+        accounts: :class:`~tradezero.modules.accounts.AsyncAccountsModule`
+        trading: :class:`~tradezero.modules.trading.AsyncTradingModule`
+        positions: :class:`~tradezero.modules.positions.AsyncPositionsModule`
+        locates: :class:`~tradezero.modules.locates.AsyncLocatesModule`
+
+    Raises:
+        ValueError: If credentials are missing from both kwargs and env vars.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        api_secret: str | None = None,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        resolved_key = api_key or api_key_from_env()
+        resolved_secret = api_secret or api_secret_from_env()
+        resolved_url = base_url or base_url_from_env()
+
+        if not resolved_key:
+            raise ValueError(
+                "api_key is required. Pass it explicitly or set the TZ_API_KEY "
+                "environment variable."
+            )
+        if not resolved_secret:
+            raise ValueError(
+                "api_secret is required. Pass it explicitly or set the TZ_API_SECRET "
+                "environment variable."
+            )
+
+        self._http = AsyncHTTPClient(
+            api_key=resolved_key,
+            api_secret=resolved_secret,
+            base_url=resolved_url,
+            timeout=timeout,
+        )
+
+        # Domain modules
+        self.accounts = AsyncAccountsModule(self._http)
+        self.trading = AsyncTradingModule(self._http)
+        self.positions = AsyncPositionsModule(self._http)
+        self.locates = AsyncLocatesModule(self._http)
+
+    async def aclose(self) -> None:
+        """Release the underlying async HTTP connection pool."""
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncTradeZeroClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()

tradezero/client/sync_client.py

@@ -0,0 +1,93 @@
+"""Synchronous top-level TradeZero client."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from tradezero.config import (
+    DEFAULT_TIMEOUT,
+    base_url_from_env,
+    api_key_from_env,
+    api_secret_from_env,
+)
+from tradezero.http.sync_http import SyncHTTPClient
+from tradezero.modules.accounts import AccountsModule
+from tradezero.modules.trading import TradingModule
+from tradezero.modules.positions import PositionsModule
+from tradezero.modules.locates import LocatesModule
+
+
+class TradeZeroClient:
+    """Synchronous entry-point for the TradeZero SDK.
+
+    Instantiate once and reuse across calls. Supports context-manager usage
+    to automatically release HTTP connections::
+
+        with TradeZeroClient(api_key="...", api_secret="...") as client:
+            accounts = client.accounts.list_accounts()
+
+    Args:
+        api_key: TradeZero API key ID.  Falls back to the ``TZ_API_KEY``
+            environment variable if omitted.
+        api_secret: TradeZero API secret key.  Falls back to ``TZ_API_SECRET``.
+        base_url: Override the default base URL.  Falls back to ``TZ_BASE_URL``
+            or ``https://webapi.tradezero.com/v1/api``.
+        timeout: Per-request timeout in seconds (default: 30).
+
+    Attributes:
+        accounts: :class:`~tradezero.modules.accounts.AccountsModule`
+        trading: :class:`~tradezero.modules.trading.TradingModule`
+        positions: :class:`~tradezero.modules.positions.PositionsModule`
+        locates: :class:`~tradezero.modules.locates.LocatesModule`
+
+    Raises:
+        ValueError: If neither keyword arguments nor environment variables
+            supply the required credentials.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        api_secret: str | None = None,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        resolved_key = api_key or api_key_from_env()
+        resolved_secret = api_secret or api_secret_from_env()
+        resolved_url = base_url or base_url_from_env()
+
+        if not resolved_key:
+            raise ValueError(
+                "api_key is required. Pass it explicitly or set the TZ_API_KEY "
+                "environment variable."
+            )
+        if not resolved_secret:
+            raise ValueError(
+                "api_secret is required. Pass it explicitly or set the TZ_API_SECRET "
+                "environment variable."
+            )
+
+        self._http = SyncHTTPClient(
+            api_key=resolved_key,
+            api_secret=resolved_secret,
+            base_url=resolved_url,
+            timeout=timeout,
+        )
+
+        # Domain modules
+        self.accounts = AccountsModule(self._http)
+        self.trading = TradingModule(self._http)
+        self.positions = PositionsModule(self._http)
+        self.locates = LocatesModule(self._http)
+
+    def close(self) -> None:
+        """Release the underlying HTTP connection pool."""
+        self._http.close()
+
+    def __enter__(self) -> "TradeZeroClient":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()

tradezero/config.py

@@ -0,0 +1,31 @@
+"""SDK configuration and constants."""
+
+from __future__ import annotations
+
+import os
+
+DEFAULT_BASE_URL: str = "https://webapi.tradezero.com/v1/api"
+
+#: Maximum number of retry attempts for transient errors.
+DEFAULT_MAX_RETRIES: int = 3
+
+#: Seconds to wait before the first retry.
+DEFAULT_RETRY_WAIT_SECONDS: float = 1.0
+
+#: HTTP timeout in seconds.
+DEFAULT_TIMEOUT: float = 30.0
+
+
+def base_url_from_env() -> str:
+    """Return the base URL, preferring the ``TZ_BASE_URL`` environment variable."""
+    return os.environ.get("TZ_BASE_URL", DEFAULT_BASE_URL)
+
+
+def api_key_from_env() -> str | None:
+    """Return the API key from ``TZ_API_KEY`` or ``None``."""
+    return os.environ.get("TZ_API_KEY")
+
+
+def api_secret_from_env() -> str | None:
+    """Return the API secret from ``TZ_API_SECRET`` or ``None``."""
+    return os.environ.get("TZ_API_SECRET")

tradezero/enums.py

@@ -0,0 +1,80 @@
+"""Enumerations used across the TradeZero API."""
+
+from enum import Enum
+
+
+# ── Order enums ───────────────────────────────────────────────────────────────
+
+
+class OrderSide(str, Enum):
+    """Direction of a trade order.
+
+    Values match the TradeZero API wire format exactly.
+    """
+
+    BUY = "Buy"
+    SELL = "Sell"
+
+
+class OrderType(str, Enum):
+    """Execution style of a trade order.
+
+    Values match the TradeZero API wire format exactly.
+    """
+
+    MARKET = "Market"
+    LIMIT = "Limit"
+    STOP = "Stop"
+    STOP_LIMIT = "StopLimit"
+
+
+class TimeInForce(str, Enum):
+    """Time-in-force instructions for a trade order.
+
+    Values match the TradeZero API wire format exactly.
+    """
+
+    DAY = "Day"
+    GTC = "GoodTillCancel"
+    IOC = "ImmediateOrCancel"
+    FOK = "FillOrKill"
+    AT_THE_OPENING = "AtTheOpening"
+    GOOD_TILL_CROSSING = "GoodTillCrossing"
+    DAY_PLUS = "Day_Plus"
+    GTC_PLUS = "GTC_Plus"
+
+
+class SecurityType(str, Enum):
+    """Type of security for an order.
+
+    Values match the TradeZero API wire format exactly.
+    """
+
+    STOCK = "Stock"
+    OPTION = "Option"
+
+
+# ── Locate enums ──────────────────────────────────────────────────────────────
+
+
+class LocateStatus(int, Enum):
+    """Integer status codes for locate requests (FIX-style)."""
+
+    NEW = 48
+    FILLED = 50
+    CANCELED = 52
+    PENDING = 54
+    REJECTED = 56
+    OFFERED = 65
+    EXPIRED = 67
+    QUOTING = 81
+
+
+class LocateTypeStr(str, Enum):
+    """Human-readable locate type strings."""
+
+    UNKNOWN = "Unknown"
+    LOCATE = "Locate"
+    INTRADAY = "IntraDay"
+    PRE_BORROW = "PreBorrow"
+    SINGLE_USE = "SingleUse"

tradezero/exceptions.py

@@ -0,0 +1,105 @@
+"""Custom exception hierarchy for the TradeZero SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class TradeZeroSDKError(Exception):
+    """Base exception for all SDK errors."""
+
+
+class TradeZeroAPIError(TradeZeroSDKError):
+    """Raised when the TradeZero API returns a non-2xx response.
+
+    Attributes:
+        status_code: HTTP status code returned by the API.
+        response_body: Raw response body text.
+        detail: Human-readable error detail extracted from the response.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        response_body: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_body = response_body
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return (
+            f"{type(self).__name__}(status_code={self.status_code!r}, "
+            f"message={str(self)!r})"
+        )
+
+
+class AuthenticationError(TradeZeroAPIError):
+    """Raised on 401 Unauthorized responses."""
+
+
+class ForbiddenError(TradeZeroAPIError):
+    """Raised on 403 Forbidden responses."""
+
+
+class NotFoundError(TradeZeroAPIError):
+    """Raised on 404 Not Found responses."""
+
+
+class RateLimitError(TradeZeroAPIError):
+    """Raised on 429 Too Many Requests responses."""
+
+
+class APIValidationError(TradeZeroAPIError):
+    """Raised on 422 Unprocessable Entity (invalid request payload)."""
+
+
+class InsufficientFundsError(TradeZeroAPIError):
+    """Raised when the account has insufficient buying power."""
+
+
+class ServerError(TradeZeroAPIError):
+    """Raised on 5xx server-side errors."""
+
+
+# ── Status-code → exception mapping ──────────────────────────────────────────
+
+_STATUS_MAP: dict[int, type[TradeZeroAPIError]] = {
+    401: AuthenticationError,
+    403: ForbiddenError,
+    404: NotFoundError,
+    422: APIValidationError,
+    429: RateLimitError,
+}
+
+
+def raise_for_status(status_code: int, body: str, url: str) -> None:
+    """Map an HTTP status code to the appropriate SDK exception and raise it.
+
+    Args:
+        status_code: HTTP status code from the API response.
+        body: Raw response body text for debugging.
+        url: Request URL for context in the error message.
+
+    Raises:
+        TradeZeroAPIError: Always raised with the most specific subclass available.
+    """
+    exc_cls = _STATUS_MAP.get(status_code)
+    if exc_cls is None:
+        exc_cls = ServerError if status_code >= 500 else TradeZeroAPIError
+
+    # Attempt to surface a friendly message from the body
+    try:
+        import json
+        data: Any = json.loads(body)
+        detail = data.get("message") or data.get("detail") or data.get("error") or body
+    except Exception:
+        detail = body or "No detail provided."
+
+    raise exc_cls(
+        f"[{status_code}] {url} — {detail}",
+        status_code=status_code,
+        response_body=body,
+    )

tradezero/http/__init__.py

@@ -0,0 +1,9 @@
+"""Low-level HTTP transport layer.
+
+Internal implementation detail — prefer importing from ``tradezero`` directly.
+"""
+
+from tradezero.http.async_http import AsyncHTTPClient
+from tradezero.http.sync_http import SyncHTTPClient
+
+__all__ = ["SyncHTTPClient", "AsyncHTTPClient"]

tradezero/http/_base.py

@@ -0,0 +1,35 @@
+"""Shared utilities and header-building logic for HTTP clients."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def build_auth_headers(api_key: str, api_secret: str) -> dict[str, str]:
+    """Return the authentication headers required by every TradeZero API request.
+
+    Args:
+        api_key: The ``TZ-API-KEY-ID`` value.
+        api_secret: The ``TZ-API-SECRET-KEY`` value.
+
+    Returns:
+        A dictionary of HTTP headers to inject into every request.
+    """
+    return {
+        "TZ-API-KEY-ID": api_key,
+        "TZ-API-SECRET-KEY": api_secret,
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+    }
+
+
+def strip_none(params: dict[str, Any]) -> dict[str, Any]:
+    """Remove keys whose value is ``None`` from a query-parameter dict.
+
+    Args:
+        params: Raw parameter mapping, possibly containing ``None`` values.
+
+    Returns:
+        A new dict with all ``None`` entries removed.
+    """
+    return {k: v for k, v in params.items() if v is not None}

tradezero/http/_retry.py

@@ -0,0 +1,69 @@
+"""Tenacity-based retry configuration shared by both HTTP clients."""
+
+from __future__ import annotations
+
+import logging
+
+import httpx
+from tenacity import (
+    RetryCallState,
+    retry,
+    retry_if_exception,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+from tradezero.config import DEFAULT_MAX_RETRIES, DEFAULT_RETRY_WAIT_SECONDS
+from tradezero.exceptions import RateLimitError, ServerError
+
+logger = logging.getLogger(__name__)
+
+
+def _is_retryable(exc: BaseException) -> bool:
+    """Return ``True`` for errors that warrant an automatic retry.
+
+    Retries are attempted for:
+
+    - ``httpx.TransportError`` (network-level failures, e.g. connection reset)
+    - :class:`~tradezero.exceptions.RateLimitError` (HTTP 429 Too Many Requests)
+    - :class:`~tradezero.exceptions.ServerError` (HTTP 5xx server-side errors)
+
+    Args:
+        exc: The exception raised by the HTTP call.
+
+    Returns:
+        ``True`` if the request should be retried.
+    """
+    if isinstance(exc, httpx.TransportError):
+        return True
+    if isinstance(exc, (RateLimitError, ServerError)):
+        return True
+    return False
+
+
+def _log_retry(retry_state: RetryCallState) -> None:
+    """Log each retry attempt at WARNING level.
+
+    Args:
+        retry_state: Tenacity state object for the current retry cycle.
+    """
+    logger.warning(
+        "TradeZero SDK — retry attempt %d/%d after error: %s",
+        retry_state.attempt_number,
+        DEFAULT_MAX_RETRIES,
+        retry_state.outcome.exception() if retry_state.outcome else "unknown",
+    )
+
+
+#: Pre-built ``@retry`` decorator used by both sync and async clients.
+sdk_retry = retry(
+    retry=retry_if_exception(_is_retryable),
+    stop=stop_after_attempt(DEFAULT_MAX_RETRIES),
+    wait=wait_exponential(
+        multiplier=DEFAULT_RETRY_WAIT_SECONDS,
+        min=DEFAULT_RETRY_WAIT_SECONDS,
+        max=60,
+    ),
+    before_sleep=_log_retry,
+    reraise=True,
+)