mt5cli 1.3.1__tar.gz → 1.3.2__tar.gz

{mt5cli-1.3.1 → mt5cli-1.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mt5cli
-Version: 1.3.1
+Version: 1.3.2
 Summary: Generic MT5 data and execution infrastructure for Python applications
 Project-URL: Repository, https://github.com/dceoy/mt5cli.git
 Author-email: dceoy <dceoy@users.noreply.github.com>

{mt5cli-1.3.1 → mt5cli-1.3.2}/docs/api/trading.md

@@ -255,9 +255,10 @@ The offset is never inferred from `latest_tick_time - now` alone. Each
 calibration sample fetches the live `symbol_info_tick()` value **and** recent
 UTC-labeled `copy_ticks_range()` data, then searches every recent copied row
 (not just the newest) for one that matches the live tick on its shared
-`bid`/`ask`/`last`/`volume` fields (with at least one agreeing positive price
-field); the newest matching row sets the resulting offset, which must align
-to a 30-minute increment within the realistic UTC-14..UTC+14 range.
+positive `bid`/`ask`/`last` fields. Volume is not used as event identity
+because latest-tick and copied-tick views can represent OTC quote volume
+differently. The newest matching row sets the resulting offset, which must
+align to a 30-minute increment within the realistic UTC-14..UTC+14 range.
 `time_msc` is preferred over second-resolution `time` on both sides when
 available.
 
@@ -304,11 +305,12 @@ symbols and calls. A cached offset is recomputed in three cases:
   future — evidence that the broker offset grew, e.g. a UTC+2 to UTC+3
   transition.
 - Periodically, at most once per `revalidation_interval_seconds` (default 5
-  minutes), a single confirming sample is taken against the still-cached
-  offset; a disagreement forces full recalibration. This is what catches a
-  broker offset _decrease_ (e.g. UTC+3 to UTC+2): the resulting normalized
-  time looks stale rather than future, which a future-skew check alone
-  cannot distinguish from ordinary quiet-market staleness.
+  minutes), configured symbols are sampled until one confirms the
+  still-cached offset. Closed or inconclusive symbols are skipped; a detected
+  disagreement forces full recalibration. This is what catches a broker
+  offset _decrease_ (e.g. UTC+3 to UTC+2): the resulting normalized time
+  looks stale rather than future, which a future-skew check alone cannot
+  distinguish from ordinary quiet-market staleness.
 
 If recalibration still cannot validate the timestamp, the snapshot fails
 closed. Failed calibrations are recorded for diagnostics but never reused;

{mt5cli-1.3.1 → mt5cli-1.3.2}/mt5cli/trading.py

@@ -1028,18 +1028,25 @@ def _match_value(value: object) -> float | None:
 def _ticks_match(live: Mapping[str, object], copied: Mapping[str, object]) -> bool:
     """Decide whether a live tick and a copied tick are the same market event.
 
-    Every field present on both sides (``bid``, ``ask``, ``last``,
-    ``volume``) must agree, and at least one positive price field must supply
-    evidence; volume agreement or all-zero prices alone are insufficient.
+    Every positive price field present on both sides must agree, and at least
+    one such field must supply evidence. ``volume`` is deliberately excluded:
+    MT5's latest-tick snapshot and copied-tick history can expose different
+    volume representations for the same quote event, especially for OTC
+    instruments whose meaningful fields are Bid and Ask.
 
     Returns:
         True when the two ticks plausibly describe the same market event.
     """
     matched_price_field = False
-    for field in (*_TICK_MATCH_PRICE_FIELDS, "volume"):
+    for field in _TICK_MATCH_PRICE_FIELDS:
         live_value = _match_value(live.get(field))
         copied_value = _match_value(copied.get(field))
-        if live_value is None or copied_value is None:
+        if (
+            live_value is None
+            or copied_value is None
+            or live_value <= 0
+            or copied_value <= 0
+        ):
             continue
         tolerance = _PRICE_MATCH_RELATIVE_TOLERANCE * max(
             1.0,
@@ -1048,8 +1055,7 @@ def _ticks_match(live: Mapping[str, object], copied: Mapping[str, object]) -> bo
         )
         if abs(live_value - copied_value) > tolerance:
             return False
-        if field in _TICK_MATCH_PRICE_FIELDS and live_value > 0:
-            matched_price_field = True
+        matched_price_field = True
     return matched_price_field
 
 
@@ -1122,7 +1128,7 @@ def _matching_ticks_newest_first(
     live-vs-copied comparison is in flight, so every recent copied row is
     searched for the same market event as ``live`` instead of assuming the
     newest copied row is the relevant one. A newer row can also
-    coincidentally share ``live``'s price/volume fields without being the
+    coincidentally share ``live``'s price fields without being the
     same event, so every match is returned for offset-plausibility
     evaluation rather than only the newest.
 
@@ -1144,7 +1150,7 @@ def _sample_clock_offset(
     """Compare one live tick against recent copied UTC ticks.
 
     Every field-matching copied tick is evaluated, newest first, so a newer
-    row that coincidentally shares the live tick's price/volume fields
+    row that coincidentally shares the live tick's price fields
     cannot shadow a plausible offset from an older exact match; recency
     only breaks ties among candidates that are themselves plausible.
 
@@ -1258,12 +1264,13 @@ class TickClockNormalizer:
                 is recomputed unconditionally (bounds DST-transition
                 staleness).
             revalidation_interval_seconds: Minimum time between opportunistic
-                single-sample checks of an otherwise still-fresh cached
-                calibration. A disagreeing sample forces full recalibration,
-                which catches an offset decrease (for example a UTC+3 to
-                UTC+2 transition) well before ``max_calibration_age_seconds``
-                would; an inconclusive or agreeing sample keeps the cached
-                calibration.
+                checks of an otherwise still-fresh cached calibration.
+                Configured symbols are sampled until one confirms the cache;
+                a disagreeing sample forces full recalibration only when none
+                confirms it. This catches an offset decrease (for example a
+                UTC+3 to UTC+2 transition) well before
+                ``max_calibration_age_seconds`` would, while a closed symbol
+                cannot hide fresh evidence from another active symbol.
             failed_calibration_retry_seconds: Minimum time between full
                 recalibration attempts after a failed calibration, so a
                 closed or illiquid market does not retry on every call.
@@ -1451,36 +1458,40 @@ class TickClockNormalizer:
         *,
         now_epoch: float,
     ) -> TickClockCalibration | None:
-        """Confirm or replace a still-fresh cached calibration with one sample.
+        """Confirm or replace a still-fresh cached calibration with live symbols.
 
         A future-skew check alone never catches a broker offset *decrease*
         (e.g. a UTC+3 to UTC+2 transition): the resulting normalized time
         looks stale rather than future, and staleness is also the expected
-        symptom of a quiet market. This periodic single-sample check is
-        symmetric evidence that also detects that case. An inconclusive
-        sample (closed market, no matching event) leaves the cached
-        calibration in place rather than discarding a still-working offset.
+        symptom of a quiet market. This periodic check probes the configured
+        symbols until one confirms the cached offset. Inconclusive samples
+        from closed markets are skipped, so one regional symbol cannot hide
+        fresh evidence from another active symbol.
 
         Returns:
             A freshly recalibrated :class:`TickClockCalibration` when the
             fresh sample disagreed with ``cached``, or ``None`` when the
             cached calibration should be kept as-is.
         """
-        sample = _sample_clock_offset(
-            self._client,
-            symbol,
-            window_seconds=self._copied_window_seconds,
-        )
         self._last_attempt_at = now_epoch
-        if (
-            sample.offset_seconds is None
-            or sample.offset_seconds == cached.offset_seconds
-        ):
+        changed_sample: tuple[str, _OffsetSample] | None = None
+        for candidate in self._symbols or (symbol,):
+            sample = _sample_clock_offset(
+                self._client,
+                candidate,
+                window_seconds=self._copied_window_seconds,
+            )
+            if sample.offset_seconds == cached.offset_seconds:
+                return None
+            if sample.offset_seconds is not None and changed_sample is None:
+                changed_sample = (candidate, sample)
+        if changed_sample is None:
             return None
+        candidate, sample = changed_sample
         _logger.warning(
             "MT5 server clock offset for %s appears to have changed from"
             " %.0f to %.0f seconds; recalibrating.",
-            symbol,
+            candidate,
             cached.offset_seconds,
             sample.offset_seconds,
         )

{mt5cli-1.3.1 → mt5cli-1.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mt5cli"
-version = "1.3.1"
+version = "1.3.2"
 description = "Generic MT5 data and execution infrastructure for Python applications"
 authors = [{name = "dceoy", email = "dceoy@users.noreply.github.com"}]
 maintainers = [{name = "dceoy", email = "dceoy@users.noreply.github.com"}]

{mt5cli-1.3.1 → mt5cli-1.3.2}/tests/test_trading.py

@@ -4795,6 +4795,88 @@ class TestTickClockNormalizer:
         _assert_close(calibration.calibrated_at, _CLOCK_NOW_EPOCH)
         assert client.copy_ticks_range.call_count == 3
 
+    def test_revalidation_uses_active_configured_symbol_when_one_is_closed(
+        self,
+        mocker: MockerFixture,
+    ) -> None:
+        """One closed symbol cannot hide fresh connection-wide evidence."""
+        mock_dt, _ = _freeze_clock(mocker)
+        event_1 = _CLOCK_NOW_EPOCH - 2
+        event_2 = _CLOCK_NOW_EPOCH - 1
+        later = datetime.fromtimestamp(_CLOCK_NOW_EPOCH + 61.0, tz=UTC)
+        later_event = later.timestamp() - 1
+        client = _clock_client(
+            [
+                _live_tick(event_1 + _UTC_PLUS_3),
+                _live_tick(event_2 + _UTC_PLUS_3, bid=150.0, ask=150.1),
+                _live_tick(event_1 + _UTC_PLUS_3),  # closed revalidation sample
+                _live_tick(later_event + _UTC_PLUS_3, bid=150.0, ask=150.1),
+                _live_tick(later_event + _UTC_PLUS_3, bid=150.0, ask=150.1),
+            ],
+            [
+                _copied_frame(event_1),
+                _copied_frame(event_2, bid=150.0, ask=150.1),
+                pd.DataFrame(),
+                _copied_frame(later_event, bid=150.0, ask=150.1),
+            ],
+        )
+        normalizer = TickClockNormalizer(
+            client,
+            ["CLOSED", "ACTIVE"],
+            samples_per_symbol=1,
+            revalidation_interval_seconds=60.0,
+        )
+        assert normalizer.calibrate().status == "calibrated"
+
+        mock_dt.now.return_value = later
+        snapshot = normalizer.get_normalized_tick_snapshot("ACTIVE")
+
+        assert snapshot["clock_status"] == "calibrated"
+        assert snapshot["time_utc"] == datetime.fromtimestamp(later_event, tz=UTC)
+        _assert_close(snapshot["server_clock_offset_seconds"], _UTC_PLUS_3)
+        assert [
+            call.kwargs["symbol"]
+            for call in client.symbol_info_tick_as_dict.call_args_list
+        ] == ["CLOSED", "ACTIVE", "CLOSED", "ACTIVE", "ACTIVE"]
+
+    def test_inconclusive_revalidation_keeps_cached_offset(
+        self,
+        mocker: MockerFixture,
+    ) -> None:
+        """A closed market does not discard a still-valid cached offset."""
+        mock_dt, _ = _freeze_clock(mocker)
+        event_1 = _CLOCK_NOW_EPOCH - 2
+        event_2 = _CLOCK_NOW_EPOCH - 1
+        later = datetime.fromtimestamp(_CLOCK_NOW_EPOCH + 61.0, tz=UTC)
+        client = _clock_client(
+            [
+                _live_tick(event_1 + _UTC_PLUS_3),
+                _live_tick(event_2 + _UTC_PLUS_3),
+                _live_tick(event_2 + _UTC_PLUS_3),
+                _live_tick(event_2 + _UTC_PLUS_3),
+            ],
+            [
+                _copied_frame(event_1),
+                _copied_frame(event_2),
+                pd.DataFrame(),
+            ],
+        )
+        normalizer = TickClockNormalizer(
+            client,
+            ["SING30"],
+            samples_per_symbol=2,
+            revalidation_interval_seconds=60.0,
+        )
+        first = normalizer.calibrate()
+        _assert_close(first.offset_seconds, _UTC_PLUS_3)
+
+        mock_dt.now.return_value = later
+        snapshot = normalizer.get_normalized_tick_snapshot("SING30")
+
+        assert snapshot["clock_status"] == "calibrated"
+        _assert_close(snapshot["server_clock_offset_seconds"], _UTC_PLUS_3)
+        assert client.copy_ticks_range.call_count == 3
+
     def test_offset_decrease_is_caught_by_periodic_revalidation(
         self,
         mocker: MockerFixture,
@@ -4913,14 +4995,12 @@ class TestTickClockNormalizer:
         [
             ({"bid": None, "ask": None, "last": None}, {}),
             ({"bid": 0.0, "ask": None, "last": None}, {"bid": 0.0}),
-            ({"volume": 6}, {}),
             ({"bid": "1.1", "ask": None, "last": None}, {}),
             ({"bid": float("nan"), "ask": None, "last": None}, {}),
         ],
         ids=[
             "volume-only",
             "zero-price-only",
-            "volume-mismatch",
             "string-price",
             "nan-price",
         ],
@@ -4948,6 +5028,57 @@ class TestTickClockNormalizer:
 
         assert normalizer.calibrate().status == "no_matching_event"
 
+    def test_volume_difference_does_not_hide_matching_quote_event(
+        self,
+        mocker: MockerFixture,
+    ) -> None:
+        """Bid/ask identity remains usable when live and copied volumes differ."""
+        _freeze_clock(mocker)
+        event = _CLOCK_NOW_EPOCH - 1
+        client = _clock_client(
+            [_live_tick(event + _UTC_PLUS_3, volume=6)],
+            _copied_frame(event, volume=5),
+        )
+        normalizer = TickClockNormalizer(
+            client,
+            ["SING30"],
+            samples_per_symbol=1,
+            min_agreeing_samples=1,
+        )
+
+        calibration = normalizer.calibrate()
+
+        assert calibration.status == "calibrated"
+        _assert_close(calibration.offset_seconds, _UTC_PLUS_3)
+
+    def test_half_hour_delayed_feed_is_not_inferred_from_host_clock(
+        self,
+        mocker: MockerFixture,
+    ) -> None:
+        """Advancing stale ticks cannot become fresh through host-time rounding."""
+        _freeze_clock(mocker)
+        delayed_event_1 = _CLOCK_NOW_EPOCH - 1802
+        delayed_event_2 = _CLOCK_NOW_EPOCH - 1801
+        copied = _copied_frame(delayed_event_1, delayed_event_2)
+        client = _clock_client(
+            [
+                _live_tick(delayed_event_1 + _UTC_PLUS_3),
+                _live_tick(delayed_event_2 + _UTC_PLUS_3),
+            ],
+            pd.DataFrame(),
+        )
+        client.copy_ticks_range.side_effect = _windowed_copy_ticks_range(copied)
+        normalizer = TickClockNormalizer(
+            client,
+            ["SING30"],
+            samples_per_symbol=2,
+        )
+
+        calibration = normalizer.calibrate()
+
+        assert calibration.status == "no_copied_ticks"
+        assert calibration.offset_seconds is None
+
     def test_copied_time_msc_datetime_and_time_fallbacks(
         self,
         mocker: MockerFixture,

{mt5cli-1.3.1 → mt5cli-1.3.2}/uv.lock

@@ -506,7 +506,7 @@ wheels = [
 
 [[package]]
 name = "mt5cli"
-version = "1.3.1"
+version = "1.3.2"
 source = { editable = "." }
 dependencies = [
     { name = "pandas" },