ctrader-api-client 0.5.0__tar.gz → 0.6.0__tar.gz

{ctrader_api_client-0.5.0 → ctrader_api_client-0.6.0}/.gitignore

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

{ctrader_api_client-0.5.0 → ctrader_api_client-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctrader-api-client
-Version: 0.5.0
+Version: 0.6.0
 Summary: API Client to interact with the cTrader Open API spec
 Author-email: Elio <elioachukri@pm.me>
 License-File: LICENSE
@@ -119,7 +119,9 @@ creds = await client.auth.authenticate_by_trader_login(
     expires_at=1778617423,
 )
 
-# Tokens are automatically refreshed before expiry
+# 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.
 ```
 
 ### Market Data
@@ -150,10 +152,10 @@ request = NewOrderRequest(
     side=OrderSide.BUY,
     volume=100000,  # 1 lot in cents
 )
-result = await client.trading.create_order(account_id, request)
+result = await client.trading.place_order(account_id, request)
 
 # Get open positions
-positions = await client.trading.get_positions(account_id)
+positions = await client.trading.get_open_positions(account_id)
 
 # Close a position
 close_position = ClosePositionRequest(
@@ -171,6 +173,7 @@ from ctrader_api_client.events import (
     ExecutionEvent,
     ReadyEvent,
     ReconnectedEvent,
+    TokenRefreshFailedEvent,
 )
 
 # Price updates
@@ -193,6 +196,12 @@ async def on_ready(event: ReadyEvent):
 @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}")
 ```
 
 ### Symbols
@@ -237,6 +246,9 @@ Use `ReadyEvent` to set up subscriptions that persist across reconnections.
 ## Configuration
 
 ```python
+from ctrader_api_client import ClientConfig
+from ctrader_api_client.auth import ReauthPolicy, RefreshPolicy
+
 config = ClientConfig(
     client_id="your_client_id",
     client_secret="your_client_secret",
@@ -255,5 +267,20 @@ config = ClientConfig(
     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,
+    ),
 )
 ```

{ctrader_api_client-0.5.0 → ctrader_api_client-0.6.0}/README.md

@@ -100,7 +100,9 @@ creds = await client.auth.authenticate_by_trader_login(
     expires_at=1778617423,
 )
 
-# Tokens are automatically refreshed before expiry
+# 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.
 ```
 
 ### Market Data
@@ -131,10 +133,10 @@ request = NewOrderRequest(
     side=OrderSide.BUY,
     volume=100000,  # 1 lot in cents
 )
-result = await client.trading.create_order(account_id, request)
+result = await client.trading.place_order(account_id, request)
 
 # Get open positions
-positions = await client.trading.get_positions(account_id)
+positions = await client.trading.get_open_positions(account_id)
 
 # Close a position
 close_position = ClosePositionRequest(
@@ -152,6 +154,7 @@ from ctrader_api_client.events import (
     ExecutionEvent,
     ReadyEvent,
     ReconnectedEvent,
+    TokenRefreshFailedEvent,
 )
 
 # Price updates
@@ -174,6 +177,12 @@ async def on_ready(event: ReadyEvent):
 @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}")
 ```
 
 ### Symbols
@@ -218,6 +227,9 @@ Use `ReadyEvent` to set up subscriptions that persist across reconnections.
 ## Configuration
 
 ```python
+from ctrader_api_client import ClientConfig
+from ctrader_api_client.auth import ReauthPolicy, RefreshPolicy
+
 config = ClientConfig(
     client_id="your_client_id",
     client_secret="your_client_secret",
@@ -236,5 +248,20 @@ config = ClientConfig(
     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,
+    ),
 )
 ```

{ctrader_api_client-0.5.0 → ctrader_api_client-0.6.0}/docs/api/client.md

@@ -27,6 +27,19 @@ The main entry point for interacting with the cTrader API.
     options:
       show_source: false
 
+## Authentication Policies
+
+Token-refresh and session-recovery timing, passed via
+`ClientConfig(refresh_policy=..., reauth_policy=...)`.
+
+::: ctrader_api_client.auth.RefreshPolicy
+    options:
+      show_source: false
+
+::: ctrader_api_client.auth.ReauthPolicy
+    options:
+      show_source: false
+
 ## Authentication
 
 The `client.auth` property provides access to authentication operations.

{ctrader_api_client-0.5.0 → ctrader_api_client-0.6.0}/docs/api/events.md

@@ -158,6 +158,15 @@ drop. Check current authorization with `client.is_account_authorized(account_id)
     options:
       show_source: false
 
+::: ctrader_api_client.events.TokenRefreshFailedEvent
+    options:
+      show_source: false
+
+The client keeps the existing credentials and retries on the next refresh check,
+so a single event usually means a transient outage. If the event keeps repeating,
+the refresh token is no longer usable and the account has to be re-authorized out
+of band.
+
 ## Symbol Events
 
 ::: ctrader_api_client.events.SymbolChangedEvent

{ctrader_api_client-0.5.0 → ctrader_api_client-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ctrader-api-client"
-version = "0.5.0"
+version = "0.6.0"
 description = "API Client to interact with the cTrader Open API spec"
 readme = "README.md"
 authors = [
@@ -32,10 +32,36 @@ dev = [
     "mkdocs-material>=9.7.6",
     "mkdocstrings[python]>=1.0.3",
     "pytest>=9.0.3",
+    "pytest-cov>=7.0.0",
+    "pytest-timeout>=2.4.0",
     "ruff>=0.15.9",
     "zuban>=0.7.0",
 ]
 
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--strict-markers --strict-config"
+# Every coroutine test runs under anyio without a per-test marker. Marking them
+# later (in a collection hook) makes anyio rebuild the item and silently drop
+# any pytest.mark.parametrize arguments.
+anyio_mode = "auto"
+# No test should ever hang: a stuck reader loop or an unresolved request must
+# fail the run rather than block it.
+timeout = 30
+filterwarnings = [
+    "error",
+    # stringcase, a transitive betterproto dependency, is unmaintained and has
+    # invalid escape sequences that newer Pythons flag on import.
+    "ignore::SyntaxWarning",
+]
+
+[tool.coverage.run]
+source = ["ctrader_api_client"]
+omit = ["*/_internal/proto/*"]
+
+[tool.coverage.report]
+exclude_also = ["if TYPE_CHECKING:", "@overload", "\\.\\.\\."]
+
 [tool.ruff]
 line-length = 120
 

{ctrader_api_client-0.5.0 → ctrader_api_client-0.6.0}/src/ctrader_api_client/_internal/__init__.py

@@ -1,8 +1,10 @@
+from .clock import Clock, MonotonicClock
+from .conversions import DEFAULT_MONEY_DIGITS, money_divisor, timestamp_to_datetime
 from .messages import (
     ClientMessageIdGenerator,
-    MessageRegistry,
     deserialize_proto_message,
-    get_registry,
+    get_class,
+    get_payload_type,
     unwrap_message,
     wrap_message,
 )
@@ -14,13 +16,18 @@ from .serialization import (
 
 
 __all__ = [
+    "DEFAULT_MONEY_DIGITS",
     "ClientMessageIdGenerator",
-    "MessageRegistry",
+    "Clock",
+    "MonotonicClock",
     "deserialize_proto_message",
     "encode_with_length_prefix",
-    "get_registry",
+    "get_class",
+    "get_payload_type",
+    "money_divisor",
     "read_exact",
     "read_framed_message",
+    "timestamp_to_datetime",
     "unwrap_message",
     "wrap_message",
 ]

ctrader_api_client-0.6.0/src/ctrader_api_client/_internal/clock.py

@@ -0,0 +1,36 @@
+"""Time source abstraction for timer-driven components."""
+
+from __future__ import annotations
+
+import time
+from typing import Protocol as TypingProtocol
+
+import anyio
+
+
+class Clock(TypingProtocol):
+    """A source of monotonic time and delays.
+
+    Injected into components whose behaviour is driven by elapsed time so that
+    those timings can be controlled deterministically instead of waited on.
+    """
+
+    def now(self) -> float:
+        """Return the current value of a monotonic clock, in seconds."""
+        ...
+
+    async def sleep(self, seconds: float) -> None:
+        """Suspend the calling task for the given number of seconds."""
+        ...
+
+
+class MonotonicClock:
+    """Default clock backed by :func:`time.monotonic` and :func:`anyio.sleep`."""
+
+    def now(self) -> float:
+        """Return the current monotonic time in seconds."""
+        return time.monotonic()
+
+    async def sleep(self, seconds: float) -> None:
+        """Suspend the calling task for the given number of seconds."""
+        await anyio.sleep(seconds)

ctrader_api_client-0.6.0/src/ctrader_api_client/_internal/conversions.py

@@ -0,0 +1,41 @@
+"""Conversions between wire representations and Python types."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+
+# The scale the server uses for monetary amounts when it does not say otherwise.
+# money_digits is a plain proto3 scalar, so a message that omits it parses as 0,
+# which would scale by 1 and overstate every amount by two orders of magnitude.
+DEFAULT_MONEY_DIGITS = 2
+
+
+def money_divisor(money_digits: int) -> int:
+    """Return the divisor that turns a scaled money integer into its real value.
+
+    Monetary amounts arrive as integers scaled by ``10 ** money_digits``. A
+    ``money_digits`` of 0 is read as absent rather than as "no scaling", because
+    the wire format cannot distinguish the two and no account quotes money in
+    whole units.
+
+    Args:
+        money_digits: The exponent reported alongside the amount, or 0 if the
+            server omitted it.
+
+    Returns:
+        The divisor to apply to the scaled integer.
+    """
+    return 10 ** (money_digits or DEFAULT_MONEY_DIGITS)
+
+
+def timestamp_to_datetime(timestamp_ms: int) -> datetime:
+    """Convert a millisecond UTC timestamp to an aware datetime.
+
+    Args:
+        timestamp_ms: Milliseconds since the Unix epoch, as sent by the server.
+
+    Returns:
+        The equivalent timezone-aware datetime in UTC.
+    """
+    return datetime.fromtimestamp(timestamp_ms / 1000, tz=UTC)

{ctrader_api_client-0.5.0 → ctrader_api_client-0.6.0}/src/ctrader_api_client/_internal/messages.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import threading
-from dataclasses import dataclass, field
 
 import betterproto
 
@@ -205,25 +204,21 @@ _PAYLOAD_TYPE_TO_CLASS: dict[int, type[betterproto.Message]] = {
 }
 
 
-@dataclass
-class MessageRegistry:
-    """Bidirectional mapping between payload_type and message class."""
+# The reverse direction, for wrapping outbound messages. Every class above maps
+# from exactly one payload type, so inverting the mapping loses nothing.
+_CLASS_TO_PAYLOAD_TYPE: dict[type[betterproto.Message], int] = {
+    cls: payload_type for payload_type, cls in _PAYLOAD_TYPE_TO_CLASS.items()
+}
 
-    payload_type_to_class: dict[int, type[betterproto.Message]] = field(default_factory=dict)
-    class_to_payload_type: dict[type[betterproto.Message], int] = field(default_factory=dict)
 
-    def get_class(self, payload_type: int) -> type[betterproto.Message] | None:
-        """Get the message class for a payload type."""
-        return self.payload_type_to_class.get(payload_type)
+def get_class(payload_type: int) -> type[betterproto.Message] | None:
+    """Get the message class for a payload type, or None if unregistered."""
+    return _PAYLOAD_TYPE_TO_CLASS.get(payload_type)
 
-    def get_payload_type(self, cls: type[betterproto.Message]) -> int | None:
-        """Get the payload type for a message class."""
-        return self.class_to_payload_type.get(cls)
 
-    def register(self, payload_type: int, cls: type[betterproto.Message]) -> None:
-        """Register a bidirectional mapping."""
-        self.payload_type_to_class[payload_type] = cls
-        self.class_to_payload_type[cls] = payload_type
+def get_payload_type(cls: type[betterproto.Message]) -> int | None:
+    """Get the payload type for a message class, or None if unregistered."""
+    return _CLASS_TO_PAYLOAD_TYPE.get(cls)
 
 
 class ClientMessageIdGenerator:
@@ -240,29 +235,6 @@ class ClientMessageIdGenerator:
             return str(self._counter)
 
 
-# Module-level singleton
-_registry: MessageRegistry | None = None
-_registry_lock = threading.Lock()
-
-
-def _build_registry() -> MessageRegistry:
-    """Build the message registry from the explicit mapping."""
-    registry = MessageRegistry()
-    for payload_type, cls in _PAYLOAD_TYPE_TO_CLASS.items():
-        registry.register(payload_type, cls)
-    return registry
-
-
-def get_registry() -> MessageRegistry:
-    """Get the lazily-initialized singleton registry."""
-    global _registry
-    if _registry is None:
-        with _registry_lock:
-            if _registry is None:
-                _registry = _build_registry()
-    return _registry
-
-
 def wrap_message(inner: betterproto.Message, client_msg_id: str | None = None) -> ProtoMessage:
     """Wrap an inner message into a ProtoMessage for transmission.
 
@@ -276,8 +248,7 @@ def wrap_message(inner: betterproto.Message, client_msg_id: str | None = None) -
     Raises:
         UnknownPayloadTypeError: If the inner message type is not registered.
     """
-    registry = get_registry()
-    payload_type = registry.get_payload_type(type(inner))
+    payload_type = get_payload_type(type(inner))
 
     if payload_type is None:
         raise UnknownPayloadTypeError(payload_type=-1)
@@ -302,8 +273,7 @@ def unwrap_message(proto_message: ProtoMessage) -> betterproto.Message:
         UnknownPayloadTypeError: If the payload type is not registered.
         DeserializationError: If deserialization fails.
     """
-    registry = get_registry()
-    cls = registry.get_class(proto_message.payload_type)
+    cls = get_class(proto_message.payload_type)
 
     if cls is None:
         raise UnknownPayloadTypeError(proto_message.payload_type)

ctrader_api_client-0.6.0/src/ctrader_api_client/api/_base.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+
+if TYPE_CHECKING:
+    from ..connection import Protocol
+
+
+class BaseAPI:
+    """Shared construction and timeout handling for API namespaces."""
+
+    def __init__(self, protocol: Protocol, default_timeout: float = 30.0) -> None:
+        """Initialize the API namespace.
+
+        Args:
+            protocol: The protocol instance for sending requests.
+            default_timeout: Default request timeout in seconds.
+        """
+        self._protocol = protocol
+        self._default_timeout = default_timeout
+
+    def _timeout(self, timeout: float | None) -> float:
+        """Resolve a per-call timeout against the configured default."""
+        return timeout or self._default_timeout

{ctrader_api_client-0.5.0 → ctrader_api_client-0.6.0}/src/ctrader_api_client/api/accounts.py

@@ -1,20 +1,14 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
-
 from .._internal.proto import (
     ProtoOATraderReq,
     ProtoOATraderRes,
 )
-from ..exceptions import APIError
 from ..models import Account
+from ._base import BaseAPI
 
 
-if TYPE_CHECKING:
-    from ..connection import Protocol
-
-
-class AccountsAPI:
+class AccountsAPI(BaseAPI):
     """Account information operations.
 
     Provides methods to retrieve account/trader details.
@@ -27,16 +21,6 @@ class AccountsAPI:
         ```
     """
 
-    def __init__(self, protocol: Protocol, default_timeout: float = 30.0) -> None:
-        """Initialize the accounts API.
-
-        Args:
-            protocol: The protocol instance for sending requests.
-            default_timeout: Default request timeout in seconds.
-        """
-        self._protocol = protocol
-        self._default_timeout = default_timeout
-
     async def get_trader(
         self,
         account_id: int,
@@ -57,15 +41,10 @@ class AccountsAPI:
         """
         request = ProtoOATraderReq(ctid_trader_account_id=account_id)
 
-        response = await self._protocol.send_request(
+        response = await self._protocol.request(
             request,
-            timeout=timeout or self._default_timeout,
+            ProtoOATraderRes,
+            timeout=self._timeout(timeout),
         )
 
-        if not isinstance(response, ProtoOATraderRes):
-            raise APIError(
-                error_code="UNEXPECTED_RESPONSE",
-                description=f"Expected ProtoOATraderRes, got {type(response).__name__}",
-            )
-
         return Account.from_proto(response.trader)