fundedops 0.1.0__tar.gz

fundedops-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.pyc
+*.pyo
+.env
+.env.local
+*.egg-info/
+.venv/
+venv/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+node_modules/
+.next/
+frontend/.next/
+backend/app/**/__pycache__/
+.worktrees/

fundedops-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: fundedops
+Version: 0.1.0
+Summary: Official Python SDK for the FundedOps API — typed accounts, positions, orders, history, and real-time streaming.
+Project-URL: Homepage, https://fundedops.com
+Project-URL: Documentation, https://api.fundedops.com/docs
+Project-URL: Source, https://github.com/fundedops/fundedops-python
+Author: FundedOps
+License: MIT
+Keywords: api,fundedops,metatrader,mt5,sdk,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: websockets>=13
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fundedops
+
+The official Python SDK for the [FundedOps API](https://api.fundedops.com/docs) —
+typed access to accounts, positions, orders, trade history, and real-time
+streaming, backed by pydantic v2 models that mirror the wire format exactly.
+
+> This file doubles as the package's [PyPI](https://pypi.org/project/fundedops/) page.
+
+## Install
+
+```bash
+pip install fundedops
+```
+
+Requires Python 3.10+.
+
+## Authentication
+
+Every request carries your API key as a bearer token
+(`Authorization: Bearer fo_...`). Create a key from the developer portal. The
+key travels in the WebSocket URL's query string — never log stream URLs.
+
+## Usage
+
+Two first-class clients with an identical method surface — synchronous
+`FundedOps` and asynchronous `AsyncFundedOps`. Every method lives under the
+`client.accounts` namespace, except `wait_until_connected` and `stream`,
+which are on the client itself.
+
+### Synchronous
+
+```python
+from fundedops import FundedOps
+
+with FundedOps(api_key="fo_live_...") as client:
+    for account in client.accounts.list():
+        print(account.id, account.state, account.connection_status)
+
+    info = client.accounts.account_information(account.id)
+    print(info.balance, info.equity, info.currency)
+
+    # Deploy and block until connected (timeout is mandatory).
+    client.accounts.deploy(account.id)
+    client.wait_until_connected(account.id, timeout=180)
+```
+
+The full lifecycle and read surface is available on `client.accounts`:
+`create`, `get`, `list`, `update`, `delete`, `deploy`, `undeploy`,
+`redeploy`, `account_information`, `positions`, `pending_orders`,
+`history_deals`, and `history_orders`.
+
+### Asynchronous
+
+`AsyncFundedOps` is the exact awaitable mirror — same constructor, same
+method names, same return types (a parity test enforces it):
+
+```python
+import asyncio
+from fundedops import AsyncFundedOps
+
+async def main():
+    async with AsyncFundedOps(api_key="fo_live_...") as client:
+        accounts = await client.accounts.list()
+        info = await client.accounts.account_information(accounts[0].id)
+        print(info.equity)
+
+asyncio.run(main())
+```
+
+### Streaming
+
+`client.stream([account_id, ...])` opens a WebSocket, subscribes each
+account, answers server pings for you, and yields typed events:
+
+```python
+from fundedops import FundedOps
+
+client = FundedOps(api_key="fo_live_...")
+for event in client.stream(["9b2c..."]):
+    if event.type == "positions_updated":
+        print("open:", len(event.updated), "closed:", event.removed_ids)
+```
+
+### Errors
+
+Every non-2xx response raises a typed exception derived from
+`FundedOpsError` (`ValidationError`, `UnauthorizedError`,
+`PaymentRequiredError`, `NotFoundError`, `RateLimitedError` with
+`retry_after`, and more), each carrying `status`, `message`, and
+`request_id`.
+
+## Documentation
+
+Full API reference and guides: https://api.fundedops.com/docs
+
+## License
+
+MIT

fundedops-0.1.0/README.md

@@ -0,0 +1,98 @@
+# fundedops
+
+The official Python SDK for the [FundedOps API](https://api.fundedops.com/docs) —
+typed access to accounts, positions, orders, trade history, and real-time
+streaming, backed by pydantic v2 models that mirror the wire format exactly.
+
+> This file doubles as the package's [PyPI](https://pypi.org/project/fundedops/) page.
+
+## Install
+
+```bash
+pip install fundedops
+```
+
+Requires Python 3.10+.
+
+## Authentication
+
+Every request carries your API key as a bearer token
+(`Authorization: Bearer fo_...`). Create a key from the developer portal. The
+key travels in the WebSocket URL's query string — never log stream URLs.
+
+## Usage
+
+Two first-class clients with an identical method surface — synchronous
+`FundedOps` and asynchronous `AsyncFundedOps`. Every method lives under the
+`client.accounts` namespace, except `wait_until_connected` and `stream`,
+which are on the client itself.
+
+### Synchronous
+
+```python
+from fundedops import FundedOps
+
+with FundedOps(api_key="fo_live_...") as client:
+    for account in client.accounts.list():
+        print(account.id, account.state, account.connection_status)
+
+    info = client.accounts.account_information(account.id)
+    print(info.balance, info.equity, info.currency)
+
+    # Deploy and block until connected (timeout is mandatory).
+    client.accounts.deploy(account.id)
+    client.wait_until_connected(account.id, timeout=180)
+```
+
+The full lifecycle and read surface is available on `client.accounts`:
+`create`, `get`, `list`, `update`, `delete`, `deploy`, `undeploy`,
+`redeploy`, `account_information`, `positions`, `pending_orders`,
+`history_deals`, and `history_orders`.
+
+### Asynchronous
+
+`AsyncFundedOps` is the exact awaitable mirror — same constructor, same
+method names, same return types (a parity test enforces it):
+
+```python
+import asyncio
+from fundedops import AsyncFundedOps
+
+async def main():
+    async with AsyncFundedOps(api_key="fo_live_...") as client:
+        accounts = await client.accounts.list()
+        info = await client.accounts.account_information(accounts[0].id)
+        print(info.equity)
+
+asyncio.run(main())
+```
+
+### Streaming
+
+`client.stream([account_id, ...])` opens a WebSocket, subscribes each
+account, answers server pings for you, and yields typed events:
+
+```python
+from fundedops import FundedOps
+
+client = FundedOps(api_key="fo_live_...")
+for event in client.stream(["9b2c..."]):
+    if event.type == "positions_updated":
+        print("open:", len(event.updated), "closed:", event.removed_ids)
+```
+
+### Errors
+
+Every non-2xx response raises a typed exception derived from
+`FundedOpsError` (`ValidationError`, `UnauthorizedError`,
+`PaymentRequiredError`, `NotFoundError`, `RateLimitedError` with
+`retry_after`, and more), each carrying `status`, `message`, and
+`request_id`.
+
+## Documentation
+
+Full API reference and guides: https://api.fundedops.com/docs
+
+## License
+
+MIT

fundedops-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fundedops"
+version = "0.1.0"
+description = "Official Python SDK for the FundedOps API — typed accounts, positions, orders, history, and real-time streaming."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "FundedOps" }]
+keywords = ["fundedops", "trading", "mt5", "metatrader", "api", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "websockets>=13",
+    "pydantic>=2.7,<3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+]
+
+[project.urls]
+Homepage = "https://fundedops.com"
+Documentation = "https://api.fundedops.com/docs"
+Source = "https://github.com/fundedops/fundedops-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fundedops"]
+
+[tool.pytest.ini_options]
+# Async client + streaming tests are plain `async def` — no per-test decorator.
+asyncio_mode = "auto"

fundedops-0.1.0/src/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-0.1.0/src/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()