ctrader-api-client 0.5.1__tar.gz → 0.7.0__tar.gz

ctrader_api_client-0.7.0/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git -C \"/home/tek/Desktop/Algo Trading/Live Trading/cTrader/ctrader-api-client\" log --oneline -10)",
+      "Bash(git add *)"
+    ]
+  }
+}

{ctrader_api_client-0.5.1 → ctrader_api_client-0.7.0}/.gitignore

@@ -11,4 +11,7 @@ wheels/
 
 # IDE-specific files
 .idea/
-.vscode/
+.vscode/
+# Test artifacts
+.coverage
+.pytest_cache/

ctrader_api_client-0.7.0/HARDENING.md

@@ -0,0 +1,251 @@
+# Architecture hardening
+
+Working notes for the `harden-architecture` branch. Everything below is against
+`master` at `8f649f2`.
+
+## Done
+
+Each item is one commit, in order.
+
+### Connection and auth lifecycle tests — `de41c4d`
+
+Edge cases the existing suite did not reach, added before any of the
+refactoring below so the refactoring had something to fail against: framing,
+reconnection, token lifecycle and client startup.
+
+### Typed request correlation — `bb66230`
+
+`Protocol` tracked in-flight requests across three parallel dicts keyed by
+message id. They could disagree. Replaced by a single object holding the event,
+the outcome and the expected response type, so a pending request is one thing
+that either exists or does not.
+
+### Event handler registration — `4131424`
+
+Registering a handler and unregistering it were written out separately at every
+call site. `on_event` now returns a disposer, and callers hold that instead of
+remembering how to undo their own registration.
+
+### Pluggable token storage — `b6dc7df`
+
+Added the `TokenStore` protocol and the option to pass one to the client. The
+client writes through it whenever tokens rotate, so a process that restarts can
+pick up where it left off rather than re-authenticating from credentials.
+
+Two things moved in passing, both breaking:
+
+- `AuthTrigger` moved from `auth/trigger.py`, which is gone, to `enums.py`. It
+  describes why a session was established, which the event types need and the
+  auth package should not own alone.
+- `ReadyEvent.is_reconnect` is now a property over a `trigger: AuthTrigger`
+  field. Reading it is unchanged; constructing a `ReadyEvent` is not.
+
+### Dead code and a start() guard — `de21183`
+
+Removed `on_handler_error()`, which nothing called. Made
+`HeartbeatManager.start()` idempotent: a second call used to overwrite the
+nursery reference and leave the first loop unreachable, so `stop()` could never
+find it.
+
+### Automatic subscription restore — `e0a3273`
+
+Subscriptions were restored by an explicit call after reconnection, which meant
+every reconnection path had to remember to make it. `MarketDataAPI` is now
+registered as a restorer and the reconnect path drives it.
+
+### TokenStore documentation — `2f17ac3`
+
+No code change. `TokenStore` is write-only by design — the library never reads
+it back, because only the caller knows which accounts a given process is
+responsible for. The name suggested otherwise, so the docstrings, the README
+example and `docs/api/client.md` now say so and show the startup branch the
+caller is expected to write.
+
+Deliberately **not** done: adding `load()` to the protocol. The library would
+have no reason to call it.
+
+### Composition root — `b3e6fb5`
+
+`CTraderClient.__init__` built eleven collaborators and wired them together,
+which made the client impossible to construct with a substitute for any one of
+them. That wiring moved verbatim to `composition.py` as `build_graph()`
+returning a frozen `ClientGraph`, and `CTraderClient.from_graph()` adopts one.
+
+Two ordering constraints in the wiring are load-bearing and are noted in the
+source: market data is built before auth because it is the restorer, and auth
+before the router because it is the recovery.
+
+Deliberately **not** done: a `build_client()` convenience wrapper.
+`build_graph` plus `from_graph` already covers it.
+
+### Lifecycle inversion — `bd92f44` — **breaking**
+
+`Protocol`, `HeartbeatManager` and `AuthManager` each held a task group handed
+to them by a `start()` call and exited by a later `stop()` call from a different
+task. `start()` replaced by `serve()`, which owns its nursery lexically and
+suspends inside it; `stop()` reduced to cancelling the scope, which is allowed
+from any task.
+
+`CTraderClient.connect()` and `.close()` are **gone**. `async with client:` is
+the only way to bring a client up. The nursery lives in the `async with` block,
+so a background loop that dies is raised out of it rather than discovered at
+shutdown.
+
+Three things fell out of this:
+
+- Every `except Exception: pass` in a `stop()` is gone; there is nothing left
+  to swallow.
+- Cleanup moved into each `serve()`'s `finally`, so cancellation now cleans up
+  as thoroughly as an orderly stop.
+- `task_group.start` rather than `start_soon` in the client means the reader is
+  provably live before anything is sent. That ordering used to be implicit.
+
+Test-side, `connected` and `serving` fixtures give the *test* ownership of the
+task group, for the same reason: a loop that dies mid-test surfaces at the end
+of it instead of vanishing.
+
+### B1 — connection supervisor — `9df080b` — **breaking**
+
+`Protocol` reported drops and recoveries through two callbacks the client set
+on it by hand, and `CTraderClient._lifecycle` knew the order transport,
+protocol, heartbeat and auth had to come up in. Both are gone.
+
+`ConnectionSupervisor` owns the transport, the protocol and the heartbeat.
+`serving()` is an async context manager rather than a `serve()`: connecting
+happens before the block is entered, so a server that is not there still raises
+`CTraderConnectionFailedError` instead of the `ExceptionGroup` a task group
+would make of it. `_lifecycle` is now the supervisor's block with auth and the
+router inside it.
+
+The callbacks became one port. `ConnectionListener` — `on_connection_lost` and
+`on_connection_restored` — is what `Protocol` reports to and what the
+supervisor fans out to. The supervisor puts the heartbeat back itself before
+notifying, because that is its own machinery rather than a listener's concern.
+
+The listener is `AuthManager`, not the client. Re-authenticating the
+application and every account after a reconnect, and reporting the outcome as
+`ReconnectedEvent`, is session work; it only lived on the client because the
+callback did. That takes ~70 lines off `client.py`, and puts the logic where
+B3's `SessionRecovery` would want it.
+
+Breaking: `Protocol.set_reconnect_handler` and `set_disconnect_handler` are
+replaced by `Protocol.set_listener`, and `AuthManager.handle_connection_lost`
+is now the private `_forget_sessions`, reached through the port.
+
+Test-side, a `make_graph` fixture hands tests the graph before the client
+adopts it, which is how the listener fan-out is exercised.
+
+### Exception shape at the client boundary — `ff6137a`
+
+Found while placing automatic application authentication. Since the lifecycle
+inversion, the task group holding the background tasks surrounds the `yield` in
+`_lifecycle`, so *every* exception leaving `async with client:` passed through
+it — and anyio wraps a lone exception as readily as a group. A caller's own
+`ValueError` came back as `ExceptionGroup: unhandled errors in a TaskGroup (1
+sub-exception)`, and `except CTraderConnectionFailedError` would have stopped
+matching anything the machinery raised.
+
+`__aenter__` and `__aexit__` now peel single-exception groups, recursively,
+since the supervisor's task group nests inside the client's. Several failures
+still arrive as a group, because that is what they are, and the block's own
+exception is returned to the caller untouched rather than re-raised.
+
+Not a break against `master`: this restores the shape callers had before the
+branch.
+
+### B3 — split AuthManager — `651da82` — **breaking**
+
+`auth/manager.py` was 751 lines doing four unrelated jobs. It is now four
+pieces, each with one:
+
+- `auth/_session.py` — `SessionStore`, joining the session state types already
+  there. It owns the dict, its invalidation and every query over it, so the
+  distinction between credentials (which outlive a link) and sessions (which do
+  not) is stated once instead of being re-derived by each collaborator.
+- `auth/_refresh.py` — `TokenRefresher`, the refresh loop, its retry policy and
+  the `TokenStore` write-through.
+- `auth/_recovery.py` — `SessionRecovery`, the reauth loop and the
+  `ConnectionListener` methods. It is also the `SessionRecovery` port the event
+  router already typed its collaborator as, so the names finally line up.
+- `auth/manager.py` — `AuthManager`, down to turning credentials into live
+  sessions.
+
+The refresher and the recovery monitor each serve themselves, so `_lifecycle`
+starts two tasks where it started one, and `AuthManager` no longer has a
+lifecycle of its own.
+
+The public surface was cut at the same time, on the rule that nothing returning
+a bare `ProtoOA` message should be public:
+
+- `authenticate_app` is called by the client as it connects, and on every
+  reconnect. A client that cannot authenticate does not open, and the failure
+  arrives as `ApplicationAuthError` thanks to the unwrapping above.
+- `authenticate_account` became `authenticate_trader`, returning nothing. The
+  `trigger` argument moved to the internal `establish`, where the refresher and
+  the recovery monitor use it.
+- `get_accounts` and `resolve_account_id` moved to `AccountsAPI` as
+  `list_by_token` and `resolve_account_id`. They are account queries, not auth.
+- `authenticate_by_trader_login` is gone with no replacement. Resolving a login
+  and authenticating an account are two steps, and the convenience of joining
+  them cost a second way to do the same thing:
+  `await client.auth.authenticate_trader(await store.load(account_id))` is now
+  the only shape, restart or not.
+
+`APIError.is_token_failure()` replaces the module-level helper, since three
+modules now need to ask.
+
+### Flat public surface — `6cc397c`
+
+The package exported `CTraderClient`, `ClientConfig` and seven of the fourteen
+enums "for easier access". The seven were an arbitrary subset: a caller reading
+`order.status`, `order.time_in_force`, `deal.status`, `symbol.trading_mode` or
+`account.access_rights` had to switch to `ctrader_api_client.enums` halfway down
+the file. `AccountCredentials`, the one type nobody can avoid constructing, sat
+two modules deep.
+
+The top level now carries what a caller names — what you construct, what you
+receive, what you catch — and the subpackages keep what the composition root
+wires. Sixty-eight names: the client and its config, the credentials and the two
+policies and the `TokenStore` protocol, every enum, every model, every event
+type, every exception. `AuthManager`, `SessionStore`, `TokenRefresher`,
+`SessionRecovery`, the emitter/publisher/router and everything under `api/`,
+`connection/` and `_internal/` stay where they are, since the client hands them
+to you already assembled.
+
+The result models are exported despite `Account`, `Order`, `Position`, `Symbol`
+and `Event` being names a trading codebase may well use itself. A name you
+receive is a name you annotate, and `import ctrader_api_client as ct` is there
+for anyone with a conflict.
+
+Additive: the subpackage paths still work. Importing costs nothing extra either,
+since `from .client import CTraderClient` already pulled the whole graph in.
+
+The `Environment` enum was deleted in passing — declared, documented, and
+referenced nowhere. `ClientConfig` takes a `host` string.
+
+## Open
+
+### Version bump and changelog
+
+The lifecycle inversion removes `connect()` and `close()` from the public API,
+and the connection supervisor replaces `Protocol.set_reconnect_handler` /
+`set_disconnect_handler` with `set_listener` and drops
+`AuthManager.handle_connection_lost`. The AuthManager split then removes
+`authenticate_app`, `authenticate_account`, `authenticate_by_trader_login`,
+`get_accounts` and `resolve_account_id` from `client.auth`, adding
+`authenticate_trader` in their place and moving the two queries to
+`client.accounts`. The `TokenStore` commit moved `AuthTrigger` out of
+`auth.trigger` into `enums`, and turned `ReadyEvent.is_reconnect` into a
+property over a new `trigger` field, which breaks anyone constructing the event
+themselves. This needs a bump from `0.6.0` and a note saying so.
+
+The flat surface is additive and breaks nobody, but the `Environment` enum it
+deleted was public, so it belongs in the same note. Nothing else on the branch
+breaks a caller.
+
+### Smaller things noticed but not acted on
+
+- `client.py` is down to 501 lines, nearly all delegation and docstrings.
+- `protocol.py` is 550 lines and does framing, correlation, dispatch and
+  reconnection. Splitting it was never discussed; noting it as an observation
+  rather than a proposal.

ctrader_api_client-0.7.0/PKG-INFO

@@ -0,0 +1,377 @@
+Metadata-Version: 2.4
+Name: ctrader-api-client
+Version: 0.7.0
+Summary: API Client to interact with the cTrader Open API spec
+Author-email: Elio <elioachukri@pm.me>
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Requires-Dist: anyio>=4.13.0
+Requires-Dist: betterproto[compiler]>=1.2.5
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: tenacity>=9.1.4
+Description-Content-Type: text/markdown
+
+# cTrader API Client
+
+A Python client for the cTrader Open API. Provides a high-level async interface for trading operations, market data subscriptions, and account management.
+
+Documentation:
+- [Library Docs](https://elioachukri.github.io/ctrader-api-client/)
+- [cTrader Open API Docs](https://help.ctrader.com/open-api/)
+
+> Note that this library is in early development. The API may change, and some features may be incomplete. Contributions and feedback are welcome!
+
+## Requirements
+
+- Python 3.12+
+- An activated cTrader Open API application with client ID and secret
+- OAuth tokens for account authentication (see below)
+
+## Installation
+
+**Using uv (recommended):**
+
+```bash
+uv add ctrader-api-client
+```
+
+**Using pip:**
+
+```bash
+pip install ctrader-api-client
+```
+
+## Quick Start
+
+```python
+import asyncio
+from ctrader_api_client import (
+    AccountCredentials,
+    ClientConfig,
+    CTraderClient,
+    ReadyEvent,
+    SpotEvent,
+)
+
+config = ClientConfig(
+    client_id="your_client_id",
+    client_secret="your_client_secret",
+)
+
+client = CTraderClient(config)
+
+
+@client.on(SpotEvent, symbol_id=270)  # US500.cash
+async def on_price(event: SpotEvent):
+    print(f"Price update: {event.bid}/{event.ask}")
+
+
+async def main():
+    async with client:
+        account_id = await client.accounts.resolve_account_id(
+            "your_access_token",
+            trader_login=12345678,
+        )
+        await client.auth.authenticate_trader(
+            AccountCredentials(
+                account_id=account_id,
+                access_token="your_access_token",
+                refresh_token="your_refresh_token",
+                expires_at=1778617423,
+            )
+        )
+
+        # Subscribe once. The client re-applies this after any reconnection.
+        await client.market_data.subscribe_spots(account_id, [270])
+
+        # Keep running to receive events
+        await asyncio.Event().wait()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## OAuth Token Generation
+
+This library requires OAuth tokens from cTrader. For simple use cases, you can use [ctrader-oauth-fetcher](https://github.com/ElioaChukri/ctrader-oauth-fetcher) to generate tokens:
+
+```bash
+uvx ctrader-oauth-fetcher --client-id [ID] --client-secret [SECRET]
+```
+
+This opens a browser for authorization and returns your access token, refresh token, and expiry time.
+
+For production applications, implement the OAuth flow according to the [cTrader Open API documentation](https://help.ctrader.com/open-api/).
+
+## Features
+
+### Authentication
+
+```python
+# The application is authenticated as the client connects.
+
+# Discover the account behind a trader login
+account_id = await client.accounts.resolve_account_id("...", trader_login=12345678)
+
+# Authenticate a trading account
+await client.auth.authenticate_trader(
+    AccountCredentials(
+        account_id=account_id,
+        access_token="...",
+        refresh_token="...",
+        expires_at=1778617423,
+    )
+)
+
+# Tokens are automatically refreshed before expiry. A refresh that fails is
+# retried on the next check rather than dropping the session, and surfaces as a
+# TokenRefreshFailedEvent so a persistently dead refresh token is observable.
+```
+
+### Persisting Rotated Tokens
+
+Every refresh issues a new access **and** refresh token, and invalidates the old
+pair immediately. Pass a `TokenStore` and the client writes each new pair through
+as it is issued:
+
+```python
+from ctrader_api_client import AccountCredentials, CTraderClient, TokenStore
+
+
+class PostgresTokenStore(TokenStore):
+    def __init__(self, pool):
+        self._pool = pool
+
+    async def save(self, credentials: AccountCredentials) -> None:
+        await self._pool.execute(
+            """
+            INSERT INTO ctrader_tokens (account_id, access_token, refresh_token, expires_at)
+            VALUES ($1, $2, $3, $4)
+            ON CONFLICT (account_id) DO UPDATE SET
+                access_token = EXCLUDED.access_token,
+                refresh_token = EXCLUDED.refresh_token,
+                expires_at = EXCLUDED.expires_at
+            """,
+            credentials.account_id,
+            credentials.access_token,
+            credentials.refresh_token,
+            credentials.expires_at,
+        )
+
+    # Not part of the protocol. The client never reads the store; you do.
+    async def load(self, account_id: int) -> AccountCredentials | None:
+        row = await self._pool.fetchrow(
+            "SELECT access_token, refresh_token, expires_at FROM ctrader_tokens WHERE account_id = $1",
+            account_id,
+        )
+        if row is None:
+            return None
+        return AccountCredentials(account_id=account_id, **dict(row))
+
+
+client = CTraderClient(config, token_store=PostgresTokenStore(pool))
+```
+
+The save happens before the new token is put to use. A save that raises aborts
+that refresh, which is reported as a `TokenRefreshFailedEvent` and retried on the
+next check interval, so a transient storage outage recovers on its own.
+
+The protocol is write-only, because writing is the half the client has to do for
+you: rotation happens mid-session, at a moment you cannot observe. Reading back is
+yours, since only you know which accounts a given process is responsible for:
+
+```python
+store = PostgresTokenStore(pool)
+client = CTraderClient(config, token_store=store)
+
+async with client:
+    stored = await store.load(account_id)
+    if stored is None:
+        stored = AccountCredentials(
+            account_id=account_id,
+            access_token="your_access_token",
+            refresh_token="your_refresh_token",
+            expires_at=1778617423,
+        )
+
+    await client.auth.authenticate_trader(stored)
+```
+
+### Market Data
+
+```python
+# Subscribe to spot prices
+await client.market_data.subscribe_spots(account_id, [symbol_id])
+
+# Subscribe to candles
+await client.market_data.subscribe_trendbars(account_id, symbol_id, TrendbarPeriod.M1)
+
+# Get historical data
+bars = await client.market_data.get_trendbars(
+    account_id, symbol_id, TrendbarPeriod.H1, from_ts, to_ts
+)
+```
+
+### Trading
+
+```python
+from ctrader_api_client import ClosePositionRequest, NewOrderRequest, OrderSide, OrderType
+
+# Place a market order
+request = NewOrderRequest(
+    symbol_id=symbol_id,
+    order_type=OrderType.MARKET,
+    side=OrderSide.BUY,
+    volume=100000,  # 1 lot in cents
+)
+result = await client.trading.place_order(account_id, request)
+
+# Get open positions
+positions = await client.trading.get_open_positions(account_id)
+
+# Close a position
+close_position = ClosePositionRequest(
+    position_id=position_id,
+    volume=100000,  # Close full volume
+)
+await client.trading.close_position(account_id, close_position)
+```
+
+### Event Handling
+
+```python
+from ctrader_api_client import (
+    ExecutionEvent,
+    ReadyEvent,
+    ReconnectedEvent,
+    SpotEvent,
+    SubscriptionRestoreFailedEvent,
+    TokenRefreshFailedEvent,
+)
+
+# Price updates
+@client.on(SpotEvent, symbol_id=270)
+async def on_spot(event: SpotEvent):
+    print(f"{event.bid}/{event.ask}")
+
+# Order executions
+@client.on(ExecutionEvent, account_id=account_id)
+async def on_execution(event: ExecutionEvent):
+    print(f"Order {event.order_id}: {event.execution_type}")
+
+# Account ready (fires on initial auth, after reconnection, and after account-disconnect recovery)
+# Subscriptions are already restored by this point; use it to reconcile your own state.
+@client.on(ReadyEvent)
+async def on_ready(event: ReadyEvent):
+    if event.is_reconnect:
+        positions = await client.trading.get_open_positions(event.account_id)
+
+# Connection restored
+@client.on(ReconnectedEvent)
+async def on_reconnected(event: ReconnectedEvent):
+    print(f"Reconnected, restored accounts: {event.restored_accounts}")
+
+# Token refresh failed (retried automatically; a repeating event means the
+# refresh token is no longer usable and the account must be re-authorized)
+@client.on(TokenRefreshFailedEvent, account_id=account_id)
+async def on_refresh_failed(event: TokenRefreshFailedEvent):
+    print(f"Token refresh failed for {event.account_id}: {event.error}")
+
+# Market data could not be re-applied after a reconnection (retried on the next one)
+@client.on(SubscriptionRestoreFailedEvent, account_id=account_id)
+async def on_restore_failed(event: SubscriptionRestoreFailedEvent):
+    print(f"Account {event.account_id} is missing market data: {event.error}")
+```
+
+### Symbols
+
+```python
+# List all symbols
+symbols = await client.symbols.list_all(account_id)
+
+# Search by name
+results = await client.symbols.search(account_id, "EUR")
+
+# Get specific symbol
+symbol = await client.symbols.get_by_id(account_id, symbol_id)
+```
+
+### Account Information
+
+```python
+# Get account details
+account = await client.accounts.get_trader(account_id)
+print(f"Balance: {account.balance}")
+```
+
+## Automatic Reconnection
+
+The client automatically handles connection drops:
+
+1. Reconnects with exponential backoff
+2. Re-authenticates the app and all accounts
+3. Re-applies each account's market data subscriptions
+4. Emits `ReadyEvent` for each restored account
+5. Emits `ReconnectedEvent` with summary of restored/failed accounts
+
+It also handles **server-side account disconnects** (e.g. a broker dropping the
+account session over the weekend while the connection stays up): the account is
+re-authenticated on the existing connection with backoff until it succeeds, its
+subscriptions are re-applied, and then a `ReadyEvent` is emitted. Account
+authorization is observable via `client.is_account_authorized(account_id)`,
+which is distinct from the transport-level `client.is_connected`.
+
+Subscribe once, when you first authenticate. The client remembers what each
+account asked for and re-applies it before announcing the account as ready, so
+do not re-subscribe from a `ReadyEvent` handler — the server rejects a duplicate
+subscription. If restoration fails it stops at the first failure and emits a
+`SubscriptionRestoreFailedEvent`, keeping the intent so the next reconnection
+tries again.
+
+## Configuration
+
+```python
+from ctrader_api_client import ClientConfig, ReauthPolicy, RefreshPolicy
+
+config = ClientConfig(
+    client_id="your_client_id",
+    client_secret="your_client_secret",
+
+    # Connection settings
+    host="live.ctraderapi.com",  # or "demo.ctraderapi.com"
+    port=5035,
+    use_ssl=True,
+
+    # Timeouts
+    heartbeat_interval=10.0,
+    heartbeat_timeout=30.0, # Or 0 to disable server heartbeat checks
+    request_timeout=30.0,
+
+    # Reconnection
+    reconnect_attempts=5,
+    reconnect_min_wait=1.0,
+    reconnect_max_wait=60.0,
+
+    # Token refresh: when to refresh access tokens and how hard to retry
+    refresh_policy=RefreshPolicy(
+        buffer_seconds=300.0,  # refresh this long before expiry
+        check_interval=60.0,   # how often to check for expiring tokens
+        retry_attempts=3,
+        retry_min_wait=1.0,
+        retry_max_wait=30.0,
+    ),
+
+    # Session recovery: backoff for re-establishing sessions the server dropped
+    reauth_policy=ReauthPolicy(
+        min_wait=1.0,
+        max_wait=60.0,
+    ),
+)
+```