ctrader-api-client 0.8.0__tar.gz → 0.8.1__tar.gz

{ctrader_api_client-0.8.0 → ctrader_api_client-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: ctrader-api-client
-Version: 0.8.0
+Version: 0.8.1
 Summary: API Client to interact with the cTrader Open API spec
 Author-email: Elio <elioachukri@pm.me>
 License-File: LICENSE
@@ -15,6 +15,7 @@ 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
+Requires-Dist: tzdata>=2025.2
 Description-Content-Type: text/markdown
 
 # cTrader API Client
@@ -301,6 +302,17 @@ results = await client.symbols.search(account_id, "EUR")
 
 # Get specific symbol
 symbol = await client.symbols.get_by_id(account_id, symbol_id)
+
+# Trading hours arrive with the symbol, so this costs no extra request
+hours = symbol.trading_hours
+if hours.is_open():
+    print(f"Open, closes at {hours.next_close()}")
+else:
+    print(f"Closed, opens at {hours.next_open()}")
+
+# Sessions for a given day, with broker holidays already applied
+for session in hours.sessions_on(date(2026, 6, 19)):
+    print(session.start, "->", session.end)
 ```
 
 ### Account Information

{ctrader_api_client-0.8.0 → ctrader_api_client-0.8.1}/README.md

@@ -282,6 +282,17 @@ results = await client.symbols.search(account_id, "EUR")
 
 # Get specific symbol
 symbol = await client.symbols.get_by_id(account_id, symbol_id)
+
+# Trading hours arrive with the symbol, so this costs no extra request
+hours = symbol.trading_hours
+if hours.is_open():
+    print(f"Open, closes at {hours.next_close()}")
+else:
+    print(f"Closed, opens at {hours.next_open()}")
+
+# Sessions for a given day, with broker holidays already applied
+for session in hours.sessions_on(date(2026, 6, 19)):
+    print(session.start, "->", session.end)
 ```
 
 ### Account Information

{ctrader_api_client-0.8.0 → ctrader_api_client-0.8.1}/docs/api/models.md

@@ -130,6 +130,26 @@ partial_close = ClosePositionRequest(
       show_source: false
 
 
+::: ctrader_api_client.models.TradingHours
+    options:
+      show_source: false
+
+
+::: ctrader_api_client.models.TradingSession
+    options:
+      show_source: false
+
+
+::: ctrader_api_client.models.ScheduleInterval
+    options:
+      show_source: false
+
+
+::: ctrader_api_client.models.Holiday
+    options:
+      show_source: false
+
+
 ::: ctrader_api_client.models.Account
     options:
       show_source: false

{ctrader_api_client-0.8.0 → ctrader_api_client-0.8.1}/docs/api/symbols.md

@@ -58,6 +58,64 @@ for sym in eur_pairs:
     print(sym.name)
 ```
 
+## Trading Hours
+
+Every `Symbol` arrives with its trading calendar attached, so asking when a symbol is open
+costs no extra request:
+
+```python
+from datetime import date
+
+symbol = await client.symbols.get_by_id(account_id, 270)
+hours = symbol.trading_hours
+
+if hours.is_open():
+    print("open now, closes at", hours.next_close())
+else:
+    print("closed, opens at", hours.next_open())
+
+for session in hours.sessions_on(date(2026, 6, 19)):
+    print(session.start, "->", session.end, f"({session.duration})")
+```
+
+Sessions are reported in the symbol's own `schedule_timezone` and are never merged, so a
+schedule with a nightly maintenance break reports one session either side of it.
+
+### Holidays
+
+Holidays are closed windows that cut into the weekly schedule rather than replacing a whole
+day. A broker publishing an "early close" sends a window covering the rest of the day, which
+brings the close forward:
+
+```python
+# Regular Friday: 01:05 - 23:50. With a 20:00 early close holiday:
+hours.sessions_on(date(2026, 6, 19))  # -> one session, 01:05 - 20:00
+
+hours.holidays_on(date(2026, 6, 19))  # -> the holiday responsible
+```
+
+A holiday carries **its own** timezone, which is not always the symbol's. A closure defined in
+a timezone an hour behind the symbol's straddles two of the symbol's calendar days, and both
+are shortened accordingly.
+
+A holiday whose window is empty (`start_second >= end_second`, which brokers send as `0`/`0`)
+closes the entire day.
+
+### Trading mode is separate
+
+`is_open()` answers the calendar question only. A symbol can be closed to trading by its
+`trading_mode` while the schedule says it is open, so check both:
+
+```python
+tradable = hours.is_open() and symbol.trading_mode == TradingMode.ENABLED
+```
+
+### Staleness
+
+Schedules arrive only with a symbol fetch, so a long-lived `Symbol` can drift. Subscribe to
+`SymbolChangedEvent` and re-fetch when the server reports a change. The API exposes no
+historical schedules — what you receive is the current configuration.
+
 ## Volume Conversion
 
 The cTrader API uses volume in "cents" (smallest volume units). The relationship between lots and volume depends on the symbol's `lot_size`:

{ctrader_api_client-0.8.0 → ctrader_api_client-0.8.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ctrader-api-client"
-version = "0.8.0"
+version = "0.8.1"
 description = "API Client to interact with the cTrader Open API spec"
 readme = "README.md"
 authors = [
@@ -20,6 +20,9 @@ dependencies = [
     "betterproto[compiler]>=1.2.5",
     "pydantic>=2.12.5",
     "tenacity>=9.1.4",
+    # Windows ships no system IANA database, which ZoneInfo needs to resolve the
+    # broker-supplied timezones that trading schedules are expressed in.
+    "tzdata>=2025.2",
 ]
 
 [build-system]

{ctrader_api_client-0.8.0 → ctrader_api_client-0.8.1}/src/ctrader_api_client/__init__.py

@@ -99,6 +99,7 @@ from .exceptions import (
     TokenExpiredError,
     TokenRefreshError,
     UnknownPayloadTypeError,
+    UnknownTimezoneError,
 )
 from .models import (
     Account,
@@ -108,13 +109,17 @@ from .models import (
     CloseDetail,
     ClosePositionRequest,
     Deal,
+    Holiday,
     NewOrderRequest,
     Order,
     Position,
     PositionUnrealizedPnL,
+    ScheduleInterval,
     Symbol,
     SymbolInfo,
     TickData,
+    TradingHours,
+    TradingSession,
     Trendbar,
 )
 
@@ -154,6 +159,7 @@ __all__ = [
     "ExecutionEvent",
     "ExecutionType",
     "FramingError",
+    "Holiday",
     "MarginCallTriggerEvent",
     "MarginChangeEvent",
     "NewOrderRequest",
@@ -170,6 +176,7 @@ __all__ = [
     "ReauthPolicy",
     "ReconnectedEvent",
     "RefreshPolicy",
+    "ScheduleInterval",
     "SpotEvent",
     "StopTriggerMethod",
     "SubscriptionRestoreFailedEvent",
@@ -184,9 +191,12 @@ __all__ = [
     "TokenRefreshFailedEvent",
     "TokenStore",
     "TraderUpdateEvent",
+    "TradingHours",
     "TradingMode",
+    "TradingSession",
     "TrailingStopChangedEvent",
     "Trendbar",
     "TrendbarPeriod",
     "UnknownPayloadTypeError",
+    "UnknownTimezoneError",
 ]

{ctrader_api_client-0.8.0 → ctrader_api_client-0.8.1}/src/ctrader_api_client/exceptions.py

@@ -255,6 +255,28 @@ class APIError(CTraderError):
         )
 
 
+# =============================================================================
+# Data Errors
+# =============================================================================
+
+
+class UnknownTimezoneError(CTraderError):
+    """A timezone named by the server is not in the IANA database.
+
+    Trading schedules are broker-supplied wall clock time, so a timezone that
+    cannot be resolved leaves every session boundary meaningless. This should
+    never happen: if it does, the broker has published a symbol whose schedule
+    timezone is misconfigured, and the schedule cannot be interpreted at all.
+    """
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        super().__init__(
+            f"Unknown schedule timezone {name!r}. This should never happen; it means the broker "
+            f"published a symbol whose schedule timezone is not a valid IANA name."
+        )
+
+
 # =============================================================================
 # Protocol Errors
 # =============================================================================

{ctrader_api_client-0.8.0 → ctrader_api_client-0.8.1}/src/ctrader_api_client/models/__init__.py

@@ -30,6 +30,7 @@ from .order import Order
 from .position import Position, PositionUnrealizedPnL
 from .requests import AmendOrderRequest, AmendPositionRequest, ClosePositionRequest, NewOrderRequest
 from .symbol import Symbol, SymbolInfo
+from .trading_hours import Holiday, ScheduleInterval, TradingHours, TradingSession
 
 
 __all__ = [
@@ -40,12 +41,16 @@ __all__ = [
     "CloseDetail",
     "ClosePositionRequest",
     "Deal",
+    "Holiday",
     "NewOrderRequest",
     "Order",
     "Position",
     "PositionUnrealizedPnL",
+    "ScheduleInterval",
     "Symbol",
     "SymbolInfo",
     "TickData",
+    "TradingHours",
+    "TradingSession",
     "Trendbar",
 ]

{ctrader_api_client-0.8.0 → ctrader_api_client-0.8.1}/src/ctrader_api_client/models/symbol.py

@@ -3,9 +3,12 @@ from __future__ import annotations
 from decimal import Decimal
 from typing import TYPE_CHECKING
 
+from pydantic import Field
+
 from .._internal.proto import ProtoOATradingMode
 from ..enums import TradingMode
 from ._base import FrozenModel
+from .trading_hours import TradingHours
 
 
 if TYPE_CHECKING:
@@ -91,6 +94,8 @@ class Symbol(FrozenModel):
         tp_distance: Minimum take profit distance.
         schedule_timezone: Timezone for trading schedule.
         measurement_units: Measurement units (e.g., "oz" for gold).
+        trading_hours: Weekly schedule and holidays describing when the symbol is
+            open. Empty for a symbol the broker publishes without a schedule.
     """
 
     symbol_id: int
@@ -114,6 +119,7 @@ class Symbol(FrozenModel):
     tp_distance: int = 0
     schedule_timezone: str = ""
     measurement_units: str = ""
+    trading_hours: TradingHours = Field(default_factory=TradingHours)
 
     def volume_to_lots(self, volume_cents: int) -> Decimal:
         """Convert volume in cents to lots.
@@ -179,4 +185,5 @@ class Symbol(FrozenModel):
             tp_distance=proto.tp_distance if proto.tp_distance else 0,
             schedule_timezone=proto.schedule_time_zone or "",
             measurement_units=proto.measurement_units or "",
+            trading_hours=TradingHours.from_proto(proto),
         )