fundedops 0.1.0__py3-none-any.whl

fundedops/__init__.py

@@ -0,0 +1,105 @@
+"""fundedops — the official Python SDK for the FundedOps API.
+
+This package ships the contract layer the HTTP and streaming clients build on:
+
+* :mod:`fundedops.models` — pydantic v2 models that mirror the camelCase wire
+  format exactly (snake_case attributes, camelCase aliases).
+* :mod:`fundedops.errors` — a typed exception hierarchy mirroring the API's
+  MetaApi-style error envelope.
+* :class:`FundedOps` / :class:`AsyncFundedOps` — the synchronous and
+  asynchronous REST + streaming clients (first-class equals, D-17).
+* :class:`Stream` / :class:`AsyncStream` — the WS event iterators returned by
+  ``client.stream(...)``.
+"""
+
+from ._async_client import AsyncFundedOps
+from ._base import DEFAULT_BASE_URL
+from ._client import FundedOps
+from ._streaming import AsyncStream, Stream, StreamClosed
+from .errors import (
+    ConflictError,
+    ForbiddenError,
+    FundedOpsError,
+    InternalError,
+    NotFoundError,
+    PaymentRequiredError,
+    RateLimitedError,
+    UnauthorizedError,
+    ValidationError,
+    raise_for_envelope,
+)
+from .models import (
+    Account,
+    AccountInformation,
+    AccountInformationEvent,
+    AccountInformationUpdatedEvent,
+    Deal,
+    DealAddedEvent,
+    DealsPage,
+    ErrorEvent,
+    Order,
+    OrdersEvent,
+    OrdersPage,
+    OrdersUpdatedEvent,
+    Page,
+    PingEvent,
+    Position,
+    PositionsEvent,
+    PositionsPage,
+    PositionsUpdatedEvent,
+    StatusEvent,
+    SyncFinishedEvent,
+    SyncStartedEvent,
+    WSEvent,
+    parse_event,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "DEFAULT_BASE_URL",
+    # Clients
+    "FundedOps",
+    "AsyncFundedOps",
+    # Streaming
+    "Stream",
+    "AsyncStream",
+    "StreamClosed",
+    # Resources
+    "Account",
+    "AccountInformation",
+    "Position",
+    "Order",
+    "Deal",
+    "Page",
+    "PositionsPage",
+    "OrdersPage",
+    "DealsPage",
+    # WebSocket events
+    "parse_event",
+    "WSEvent",
+    "SyncStartedEvent",
+    "SyncFinishedEvent",
+    "AccountInformationEvent",
+    "AccountInformationUpdatedEvent",
+    "PositionsEvent",
+    "PositionsUpdatedEvent",
+    "OrdersEvent",
+    "OrdersUpdatedEvent",
+    "DealAddedEvent",
+    "StatusEvent",
+    "PingEvent",
+    "ErrorEvent",
+    # Errors
+    "raise_for_envelope",
+    "FundedOpsError",
+    "ValidationError",
+    "UnauthorizedError",
+    "PaymentRequiredError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitedError",
+    "InternalError",
+]

fundedops/_async_client.py

@@ -0,0 +1,222 @@
+"""Asynchronous FundedOps client over ``httpx.AsyncClient``.
+
+A method-for-method mirror of :mod:`fundedops._client` — same names, same
+signatures, awaitable. D-17 makes the async client a first-class equal, so any
+method present in one and absent from the other is a defect; ``test_async_client``
+introspects both classes and asserts the public method sets are identical. All
+request/param/body/parse logic is shared through :mod:`fundedops._base`, so this
+module only adds ``await`` around the network boundary.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any
+
+import httpx
+
+from . import _base
+from ._base import UNSET, DEFAULT_BASE_URL, DEFAULT_TIMEOUT
+from .errors import raise_for_envelope
+from .models import Account, AccountInformation, DealsPage, OrdersPage, PositionsPage
+
+
+class _AsyncAccounts:
+    """The async ``client.accounts`` namespace — mirrors ``_client._Accounts``."""
+
+    def __init__(self, client: "AsyncFundedOps") -> None:
+        self._client = client
+
+    # --- lifecycle ---------------------------------------------------------
+
+    async def list(
+        self,
+        offset: int = 0,
+        limit: int | None = None,
+        state: str | None = None,
+        tags: str | None = None,
+    ) -> list[Account]:
+        data = await self._client._request(
+            _base.list_accounts_spec(offset, limit, state, tags)
+        )
+        return _base.parse_accounts(data)
+
+    async def create(
+        self,
+        login: str,
+        password: str,
+        server: str,
+        platform: str,
+        name: str | None = None,
+        tags: list[str] | None = None,
+        metadata: dict | None = None,
+    ) -> Account:
+        data = await self._client._request(
+            _base.create_account_spec(
+                login, password, server, platform, name, tags, metadata
+            )
+        )
+        return _base.parse_account(data)
+
+    async def get(self, account_id: str) -> Account:
+        return _base.parse_account(
+            await self._client._request(_base.get_account_spec(account_id))
+        )
+
+    async def update(
+        self,
+        account_id: str,
+        name: Any = UNSET,
+        tags: Any = UNSET,
+        metadata: Any = UNSET,
+    ) -> Account:
+        return _base.parse_account(
+            await self._client._request(
+                _base.update_account_spec(account_id, name, tags, metadata)
+            )
+        )
+
+    async def delete(self, account_id: str) -> Account:
+        return _base.parse_account(
+            await self._client._request(_base.delete_account_spec(account_id))
+        )
+
+    async def deploy(self, account_id: str) -> Account:
+        return _base.parse_account(
+            await self._client._request(_base.deploy_spec(account_id))
+        )
+
+    async def undeploy(self, account_id: str) -> Account:
+        return _base.parse_account(
+            await self._client._request(_base.undeploy_spec(account_id))
+        )
+
+    async def redeploy(self, account_id: str) -> Account:
+        return _base.parse_account(
+            await self._client._request(_base.redeploy_spec(account_id))
+        )
+
+    # --- reads -------------------------------------------------------------
+
+    async def account_information(self, account_id: str) -> AccountInformation:
+        return _base.parse_account_information(
+            await self._client._request(_base.account_information_spec(account_id))
+        )
+
+    async def positions(self, account_id: str) -> PositionsPage:
+        return _base.parse_positions_page(
+            await self._client._request(_base.positions_spec(account_id))
+        )
+
+    async def pending_orders(self, account_id: str) -> OrdersPage:
+        return _base.parse_orders_page(
+            await self._client._request(_base.pending_orders_spec(account_id))
+        )
+
+    async def history_deals(
+        self,
+        account_id: str,
+        start_time: str | None = None,
+        end_time: str | None = None,
+        ticket: str | None = None,
+        position: str | None = None,
+        offset: int = 0,
+        limit: int | None = None,
+    ) -> DealsPage:
+        return _base.parse_deals_page(
+            await self._client._request(
+                _base.history_deals_spec(
+                    account_id, start_time, end_time, ticket, position, offset, limit
+                )
+            )
+        )
+
+    async def history_orders(
+        self,
+        account_id: str,
+        start_time: str | None = None,
+        end_time: str | None = None,
+        ticket: str | None = None,
+        position: str | None = None,
+        offset: int = 0,
+        limit: int | None = None,
+    ) -> OrdersPage:
+        return _base.parse_orders_page(
+            await self._client._request(
+                _base.history_orders_spec(
+                    account_id, start_time, end_time, ticket, position, offset, limit
+                )
+            )
+        )
+
+
+class AsyncFundedOps:
+    """Asynchronous FundedOps API client — the awaitable mirror of
+    :class:`fundedops.FundedOps`. Same constructor, same method surface."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url
+        self._http = httpx.AsyncClient(
+            base_url=base_url,
+            headers=_base.build_headers(api_key),
+            timeout=timeout,
+            transport=transport,
+        )
+        self.accounts = _AsyncAccounts(self)
+
+    async def _request(self, spec: _base.RequestSpec) -> Any:
+        """Await one RequestSpec, translate any error envelope, return the decoded
+        JSON body — the single point every response flows through
+        ``raise_for_envelope`` (mirrors the sync client)."""
+        response = await self._http.request(
+            spec.method, spec.path, params=spec.params, json=spec.json
+        )
+        raise_for_envelope(response)
+        return response.json()
+
+    async def wait_until_connected(
+        self, account_id: str, timeout: float, interval: float = 2.0
+    ) -> Account:
+        """Await polling of ``GET /v1/accounts/{id}`` until connected (D-16).
+
+        Raises :class:`TimeoutError` past ``timeout`` (T-19-16 — mandatory bound).
+        ``interval=0`` keeps tests free of real awaits between polls."""
+        deadline = time.monotonic() + timeout
+        while True:
+            account = await self.accounts.get(account_id)
+            if account.connection_status == "connected":
+                return account
+            if time.monotonic() >= deadline:
+                raise TimeoutError(
+                    f"account {account_id} did not connect within {timeout}s "
+                    f"(last connectionStatus={account.connection_status!r})"
+                )
+            if interval:
+                await asyncio.sleep(interval)
+
+    def stream(self, account_ids: list[str]):
+        """Open a WS stream and async-iterate typed events for ``account_ids``.
+
+        Returns an async-iterable :class:`fundedops._streaming.AsyncStream`
+        (imported lazily so the REST client carries no import-time websockets
+        dependency)."""
+        from ._streaming import AsyncStream
+
+        return AsyncStream(self._base_url, self._api_key, account_ids)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncFundedOps":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()

fundedops/_base.py

@@ -0,0 +1,230 @@
+"""Shared SDK internals — the single source of truth both clients build on.
+
+The synchronous (:mod:`fundedops._client`) and asynchronous
+(:mod:`fundedops._async_client`) clients differ ONLY in ``await``: every path,
+query param, request body, and response-parse decision lives here so the two
+surfaces cannot drift (D-17 requires them to be first-class equals). Each public
+client method maps to one :func:`RequestSpec` builder below plus one parser.
+
+Security: the ``Authorization: Bearer fo_...`` header is built here (T-19-15 —
+the default base URL is hardcoded ``https://`` so the key only ever leaves over
+TLS unless the caller explicitly overrides ``base_url``).
+"""
+
+from __future__ import annotations
+
+from typing import Any, NamedTuple
+
+from .models import (
+    Account,
+    AccountInformation,
+    DealsPage,
+    OrdersPage,
+    PositionsPage,
+)
+
+DEFAULT_BASE_URL = "https://api.fundedops.com"
+DEFAULT_TIMEOUT = 30.0
+
+# The mounted public sub-app lives under /v1 (backend app.mount("/v1", public_app)).
+_V1 = "/v1"
+
+# Sentinel distinguishing "field omitted from a PATCH" from an explicit ``None``
+# / empty value the caller wants to send (mirrors the backend's
+# model_fields_set / exclude_unset semantics in UpdateAccountRequest).
+UNSET: Any = object()
+
+
+class RequestSpec(NamedTuple):
+    """A pure description of one HTTP call. The clients turn it into a real
+    request; nothing here touches the network, so it is trivially testable and
+    identical across sync and async."""
+
+    method: str
+    path: str
+    params: dict[str, Any] | None = None
+    json: dict[str, Any] | None = None
+
+
+def build_headers(api_key: str) -> dict[str, str]:
+    """The confirmed public auth scheme (backend auth.py::_extract_key):
+    ``Authorization: Bearer fo_...``."""
+    return {"Authorization": f"Bearer {api_key}"}
+
+
+def _clean(mapping: dict[str, Any]) -> dict[str, Any]:
+    """Drop keys whose value is ``None`` or the :data:`UNSET` sentinel — used for
+    optional query params and optional create fields."""
+    return {k: v for k, v in mapping.items() if v is not None and v is not UNSET}
+
+
+def ws_stream_url(base_url: str, api_key: str) -> str:
+    """The ``wss://.../v1/stream?api_key=`` URL (backend ws_auth.py query auth).
+
+    http(s) → ws(s); the key rides the query string, so this string must NEVER be
+    logged (T-19-07 — enforced by the grep gate in the streaming module)."""
+    base = base_url.rstrip("/")
+    if base.startswith("https://"):
+        base = "wss://" + base[len("https://") :]
+    elif base.startswith("http://"):
+        base = "ws://" + base[len("http://") :]
+    return f"{base}{_V1}/stream?api_key={api_key}"
+
+
+# --- REST request-spec builders (one per public method) ---------------------
+
+
+def list_accounts_spec(
+    offset: int = 0,
+    limit: int | None = None,
+    state: str | None = None,
+    tags: str | None = None,
+) -> RequestSpec:
+    params = _clean({"offset": offset, "limit": limit, "state": state, "tags": tags})
+    return RequestSpec("GET", f"{_V1}/accounts", params=params)
+
+
+def create_account_spec(
+    login: str,
+    password: str,
+    server: str,
+    platform: str,
+    name: str | None = None,
+    tags: list[str] | None = None,
+    metadata: dict | None = None,
+) -> RequestSpec:
+    body = _clean(
+        {
+            "login": login,
+            "password": password,
+            "server": server,
+            "platform": platform,
+            "name": name,
+            "tags": tags,
+            "metadata": metadata,
+        }
+    )
+    return RequestSpec("POST", f"{_V1}/accounts", json=body)
+
+
+def get_account_spec(account_id: str) -> RequestSpec:
+    return RequestSpec("GET", f"{_V1}/accounts/{account_id}")
+
+
+def update_account_spec(
+    account_id: str,
+    name: Any = UNSET,
+    tags: Any = UNSET,
+    metadata: Any = UNSET,
+) -> RequestSpec:
+    # Send only the fields the caller actually set (UNSET → omit); an explicit
+    # ``None``/``[]``/``{}`` is a real value and is forwarded.
+    body = {
+        k: v
+        for k, v in {"name": name, "tags": tags, "metadata": metadata}.items()
+        if v is not UNSET
+    }
+    return RequestSpec("PATCH", f"{_V1}/accounts/{account_id}", json=body)
+
+
+def delete_account_spec(account_id: str) -> RequestSpec:
+    return RequestSpec("DELETE", f"{_V1}/accounts/{account_id}")
+
+
+def deploy_spec(account_id: str) -> RequestSpec:
+    return RequestSpec("POST", f"{_V1}/accounts/{account_id}/deploy")
+
+
+def undeploy_spec(account_id: str) -> RequestSpec:
+    return RequestSpec("POST", f"{_V1}/accounts/{account_id}/undeploy")
+
+
+def redeploy_spec(account_id: str) -> RequestSpec:
+    return RequestSpec("POST", f"{_V1}/accounts/{account_id}/redeploy")
+
+
+def account_information_spec(account_id: str) -> RequestSpec:
+    return RequestSpec("GET", f"{_V1}/accounts/{account_id}/account-information")
+
+
+def positions_spec(account_id: str) -> RequestSpec:
+    return RequestSpec("GET", f"{_V1}/accounts/{account_id}/positions")
+
+
+def pending_orders_spec(account_id: str) -> RequestSpec:
+    return RequestSpec("GET", f"{_V1}/accounts/{account_id}/orders")
+
+
+def history_deals_spec(
+    account_id: str,
+    start_time: str | None = None,
+    end_time: str | None = None,
+    ticket: str | None = None,
+    position: str | None = None,
+    offset: int = 0,
+    limit: int | None = None,
+) -> RequestSpec:
+    params = _clean(
+        {
+            "start_time": start_time,
+            "end_time": end_time,
+            "ticket": ticket,
+            "position": position,
+            "offset": offset if offset else None,
+            "limit": limit,
+        }
+    )
+    return RequestSpec(
+        "GET", f"{_V1}/accounts/{account_id}/history-deals", params=params
+    )
+
+
+def history_orders_spec(
+    account_id: str,
+    start_time: str | None = None,
+    end_time: str | None = None,
+    ticket: str | None = None,
+    position: str | None = None,
+    offset: int = 0,
+    limit: int | None = None,
+) -> RequestSpec:
+    params = _clean(
+        {
+            "start_time": start_time,
+            "end_time": end_time,
+            "ticket": ticket,
+            "position": position,
+            "offset": offset if offset else None,
+            "limit": limit,
+        }
+    )
+    return RequestSpec(
+        "GET", f"{_V1}/accounts/{account_id}/history-orders", params=params
+    )
+
+
+# --- Response parsers (shared so sync/async return identical types) ---------
+
+
+def parse_account(data: Any) -> Account:
+    return Account.model_validate(data)
+
+
+def parse_accounts(data: Any) -> list[Account]:
+    return [Account.model_validate(row) for row in data]
+
+
+def parse_account_information(data: Any) -> AccountInformation:
+    return AccountInformation.model_validate(data)
+
+
+def parse_positions_page(data: Any) -> PositionsPage:
+    return PositionsPage.model_validate(data)
+
+
+def parse_orders_page(data: Any) -> OrdersPage:
+    return OrdersPage.model_validate(data)
+
+
+def parse_deals_page(data: Any) -> DealsPage:
+    return DealsPage.model_validate(data)