mt5cli 1.2.2__tar.gz → 1.2.3__tar.gz

{mt5cli-1.2.2 → mt5cli-1.2.3}/.github/workflows/ci.yml

@@ -50,6 +50,21 @@ jobs:
     with:
       package-path: .
       runs-on: windows-latest
+  minimum-dependency-smoke-test:
+    if: >
+      github.event_name == 'push'
+      || github.event_name == 'pull_request'
+      || (github.event_name == 'workflow_dispatch' && inputs.workflow == 'lint-and-test')
+    permissions:
+      contents: read
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.2
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78  # v7.6.0
+      - name: Check CLI help with minimum Click and Typer versions
+        run: uv run --with click==8.4.0 --with typer==0.26.0 mt5cli --help
   python-docs-deploy:
     if: >
       github.event_name == 'push'

{mt5cli-1.2.2 → mt5cli-1.2.3}/AGENTS.md

@@ -26,7 +26,7 @@ Apply KISS, DRY, and YAGNI when changing code. Prefer the simplest implementatio
 
 ## Testing Guidelines
 
-Tests use pytest, pytest-mock, doctests, and pytest-cov. Test files should match `tests/test_*.py`, classes `Test*`, and functions `test_*`. Coverage is configured with `fail_under = 100`, so add focused tests for every behavior change. Mock MT5/pdmt5 boundaries; do not require a live MetaTrader terminal in unit tests.
+Tests use pytest, pytest-mock, doctests, and pytest-cov. Test files should match `tests/test_*.py`, classes `Test*`, and functions `test_*`. Parametrize unit tests with `pytest.mark.parametrize` when the same behavior needs coverage across multiple inputs. Coverage is configured with `fail_under = 100`, so add focused tests for every behavior change. Mock MT5/pdmt5 boundaries; do not require a live MetaTrader terminal in unit tests.
 
 ## Commit & Pull Request Guidelines
 

{mt5cli-1.2.2 → mt5cli-1.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mt5cli
-Version: 1.2.2
+Version: 1.2.3
 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>
@@ -16,10 +16,10 @@ Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Office/Business :: Financial :: Investment
 Requires-Python: <3.14,>=3.11
-Requires-Dist: click>=8.1.0
+Requires-Dist: click>=8.4
 Requires-Dist: pandas>=2.2.2
 Requires-Dist: pdmt5>=1.2.0
-Requires-Dist: typer>=0.15.0
+Requires-Dist: typer>=0.26.0
 Provides-Extra: otel
 Requires-Dist: opentelemetry-api; extra == 'otel'
 Requires-Dist: opentelemetry-exporter-otlp-proto-http; extra == 'otel'

{mt5cli-1.2.2 → mt5cli-1.2.3}/docs/api/trading.md

@@ -202,19 +202,24 @@ or `None` result from the underlying client is normalized to an empty DataFrame.
 Downstream packages own all strategy-specific transformations. mt5cli does not
 provide entry-deal classification, Kelly sizing, or any betting-specific helpers.
 
-## Broker server clock offset
+## Timestamp sources and broker clock offsets
 
-MT5 tick, bar, and deal timestamps are epoch values labeled in the broker
-server's wall clock, which is commonly UTC+2 or UTC+3 rather than true UTC.
-Any code that mixes those timestamps with true UTC (freshness checks,
-trailing history windows) silently inherits the broker's offset as a bias
-unless it is measured and applied explicitly.
+The MT5 Python documentation describes tick and bar data copied by the
+`copy_ticks_*` and `copy_rates_*` functions as UTC. It does not document a
+different timezone contract for `symbol_info_tick()`, nor should deal epochs
+be assumed to use a broker wall clock without source-specific evidence.
+
+`get_tick_snapshot()` preserves the numeric MT5 epoch value in `time`; it does
+not expose pdmt5's timezone-naive `Timestamp` conversion or alter the instant.
+Any broker-specific offset handling therefore requires evidence from the live
+data source in use and must be applied separately. Do not subtract a presumed
+UTC+2 or UTC+3 offset from timestamps that are already UTC.
 
 `estimate_server_clock_offset_seconds()` reads the latest tick for a symbol
 and returns the broker's clock offset from true UTC, rounded to the nearest
-half hour, or `None` when no valid tick time is available. Apply the result in
-the downstream time-window calculation when comparing broker timestamps to
-true UTC.
+half hour, or `None` when no valid tick time is available. Use it to validate a
+suspected offset for the live `symbol_info_tick()` source before applying the
+result in downstream time-window calculations.
 
 No offset is applied automatically by history retrieval helpers.
 

{mt5cli-1.2.2 → mt5cli-1.2.3}/mt5cli/cli.py

@@ -51,7 +51,7 @@ logger = logging.getLogger(__name__)
 # ---------------------------------------------------------------------------
 
 
-class _DateTimeType(click.ParamType):
+class _DateTimeType(click.ParamType[datetime]):
     """Click parameter type for ISO 8601 datetime strings."""
 
     name = "DATETIME"
@@ -59,8 +59,8 @@ class _DateTimeType(click.ParamType):
     def convert(
         self,
         value: object,
-        param: click.Parameter | None,
-        ctx: click.Context | None,
+        param: click.Parameter | None = None,
+        ctx: click.Context | None = None,
     ) -> datetime:
         """Convert a string value to a timezone-aware datetime.
 
@@ -80,7 +80,7 @@ class _DateTimeType(click.ParamType):
             self.fail(str(exc), param, ctx)
 
 
-class _TimeframeType(click.ParamType):
+class _TimeframeType(click.ParamType[int]):
     """Click parameter type for MT5 timeframe values."""
 
     name = "TIMEFRAME"
@@ -88,8 +88,8 @@ class _TimeframeType(click.ParamType):
     def convert(
         self,
         value: object,
-        param: click.Parameter | None,
-        ctx: click.Context | None,
+        param: click.Parameter | None = None,
+        ctx: click.Context | None = None,
     ) -> int:
         """Convert a string or integer value to a timeframe integer.
 
@@ -107,7 +107,7 @@ class _TimeframeType(click.ParamType):
             self.fail(str(exc), param, ctx)
 
 
-class _TickFlagsType(click.ParamType):
+class _TickFlagsType(click.ParamType[int]):
     """Click parameter type for MT5 tick copy flags."""
 
     name = "FLAGS"
@@ -115,8 +115,8 @@ class _TickFlagsType(click.ParamType):
     def convert(
         self,
         value: object,
-        param: click.Parameter | None,
-        ctx: click.Context | None,
+        param: click.Parameter | None = None,
+        ctx: click.Context | None = None,
     ) -> int:
         """Convert a string or integer value to a tick flags integer.
 
@@ -134,7 +134,7 @@ class _TickFlagsType(click.ParamType):
             self.fail(str(exc), param, ctx)
 
 
-class _RequestType(click.ParamType):
+class _RequestType(click.ParamType[dict[str, Any]]):
     """Click parameter type for JSON order requests."""
 
     name = "REQUEST"
@@ -142,8 +142,8 @@ class _RequestType(click.ParamType):
     def convert(
         self,
         value: object,
-        param: click.Parameter | None,
-        ctx: click.Context | None,
+        param: click.Parameter | None = None,
+        ctx: click.Context | None = None,
     ) -> dict[str, Any]:
         """Convert a raw CLI value to an order request dictionary.
 
@@ -166,6 +166,35 @@ TIMEFRAME_TYPE = _TimeframeType()
 TICK_FLAGS_TYPE = _TickFlagsType()
 REQUEST_TYPE = _RequestType()
 
+
+def _parse_datetime_parameter(value: str) -> datetime:
+    try:
+        return parse_datetime(value)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+
+def _parse_timeframe_parameter(value: str) -> int:
+    try:
+        return parse_timeframe(value)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+
+def _parse_tick_flags_parameter(value: str) -> int:
+    try:
+        return parse_tick_flags(value)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+
+def _parse_request_parameter(value: str) -> dict[str, Any]:
+    try:
+        return parse_request(value)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+
 # ---------------------------------------------------------------------------
 # Export context
 # ---------------------------------------------------------------------------
@@ -363,14 +392,14 @@ def rates_from(
     timeframe: Annotated[
         int,
         typer.Option(
-            click_type=TIMEFRAME_TYPE,
+            parser=_parse_timeframe_parameter,
             help="Timeframe (e.g., M1, H1, D1, or integer).",
         ),
     ],
     date_from: Annotated[
         datetime,
         typer.Option(
-            click_type=DATETIME_TYPE,
+            parser=_parse_datetime_parameter,
             help="Start date in ISO 8601 format.",
         ),
     ],
@@ -390,7 +419,7 @@ def rates_from_pos(
     timeframe: Annotated[
         int,
         typer.Option(
-            click_type=TIMEFRAME_TYPE,
+            parser=_parse_timeframe_parameter,
             help="Timeframe.",
         ),
     ],
@@ -416,7 +445,7 @@ def latest_rates(
     timeframe: Annotated[
         int,
         typer.Option(
-            click_type=TIMEFRAME_TYPE,
+            parser=_parse_timeframe_parameter,
             help="Timeframe.",
         ),
     ],
@@ -445,17 +474,17 @@ def rates_range(
     timeframe: Annotated[
         int,
         typer.Option(
-            click_type=TIMEFRAME_TYPE,
+            parser=_parse_timeframe_parameter,
             help="Timeframe.",
         ),
     ],
     date_from: Annotated[
         datetime,
-        typer.Option(click_type=DATETIME_TYPE, help="Start date."),
+        typer.Option(parser=_parse_datetime_parameter, help="Start date."),
     ],
     date_to: Annotated[
         datetime,
-        typer.Option(click_type=DATETIME_TYPE, help="End date."),
+        typer.Option(parser=_parse_datetime_parameter, help="End date."),
     ],
 ) -> None:
     """Export rates for a date range."""
@@ -471,13 +500,13 @@ def ticks_from(
     symbol: Annotated[str, typer.Option(help="Symbol name.")],
     date_from: Annotated[
         datetime,
-        typer.Option(click_type=DATETIME_TYPE, help="Start date."),
+        typer.Option(parser=_parse_datetime_parameter, help="Start date."),
     ],
     count: Annotated[int, typer.Option(help="Number of ticks.")],
     flags: Annotated[
         int,
         typer.Option(
-            click_type=TICK_FLAGS_TYPE,
+            parser=_parse_tick_flags_parameter,
             help="Tick flags (ALL, INFO, TRADE, or integer).",
         ),
     ],
@@ -495,15 +524,15 @@ def ticks_range(
     symbol: Annotated[str, typer.Option(help="Symbol name.")],
     date_from: Annotated[
         datetime,
-        typer.Option(click_type=DATETIME_TYPE, help="Start date."),
+        typer.Option(parser=_parse_datetime_parameter, help="Start date."),
     ],
     date_to: Annotated[
         datetime,
-        typer.Option(click_type=DATETIME_TYPE, help="End date."),
+        typer.Option(parser=_parse_datetime_parameter, help="End date."),
     ],
     flags: Annotated[
         int,
-        typer.Option(click_type=TICK_FLAGS_TYPE, help="Tick flags."),
+        typer.Option(parser=_parse_tick_flags_parameter, help="Tick flags."),
     ],
 ) -> None:
     """Export ticks for a date range."""
@@ -523,7 +552,7 @@ def ticks_recent(
     ],
     date_to: Annotated[
         datetime | None,
-        typer.Option(click_type=DATETIME_TYPE, help="Window end date."),
+        typer.Option(parser=_parse_datetime_parameter, help="Window end date."),
     ] = None,
     count: Annotated[
         int,
@@ -532,7 +561,7 @@ def ticks_recent(
     flags: Annotated[
         int,
         typer.Option(
-            click_type=TICK_FLAGS_TYPE,
+            parser=_parse_tick_flags_parameter,
             help="Tick flags (ALL, INFO, TRADE, or integer).",
         ),
     ] = "ALL",  # pyright: ignore[reportArgumentType]
@@ -625,11 +654,11 @@ def history_orders(
     ctx: typer.Context,
     date_from: Annotated[
         datetime | None,
-        typer.Option(click_type=DATETIME_TYPE, help="Start date."),
+        typer.Option(parser=_parse_datetime_parameter, help="Start date."),
     ] = None,
     date_to: Annotated[
         datetime | None,
-        typer.Option(click_type=DATETIME_TYPE, help="End date."),
+        typer.Option(parser=_parse_datetime_parameter, help="End date."),
     ] = None,
     group: Annotated[str | None, typer.Option(help="Group filter.")] = None,
     symbol: Annotated[str | None, typer.Option(help="Symbol filter.")] = None,
@@ -655,11 +684,11 @@ def history_deals(
     ctx: typer.Context,
     date_from: Annotated[
         datetime | None,
-        typer.Option(click_type=DATETIME_TYPE, help="Start date."),
+        typer.Option(parser=_parse_datetime_parameter, help="Start date."),
     ] = None,
     date_to: Annotated[
         datetime | None,
-        typer.Option(click_type=DATETIME_TYPE, help="End date."),
+        typer.Option(parser=_parse_datetime_parameter, help="End date."),
     ] = None,
     group: Annotated[str | None, typer.Option(help="Group filter.")] = None,
     symbol: Annotated[str | None, typer.Option(help="Symbol filter.")] = None,
@@ -686,7 +715,7 @@ def recent_history_deals(
     hours: Annotated[float, typer.Option(help="Lookback window in hours.")],
     date_to: Annotated[
         datetime | None,
-        typer.Option(click_type=DATETIME_TYPE, help="Window end date."),
+        typer.Option(parser=_parse_datetime_parameter, help="Window end date."),
     ] = None,
     group: Annotated[str | None, typer.Option(help="Group filter.")] = None,
     symbol: Annotated[str | None, typer.Option(help="Symbol filter.")] = None,
@@ -744,7 +773,7 @@ def order_check(
     ctx: typer.Context,
     request: Annotated[
         dict[str, Any],
-        typer.Option(click_type=REQUEST_TYPE, help=_REQUEST_OPTION_HELP),
+        typer.Option(parser=_parse_request_parameter, help=_REQUEST_OPTION_HELP),
     ],
 ) -> None:
     """Check funds sufficiency for a trading operation."""
@@ -756,7 +785,7 @@ def order_send(
     ctx: typer.Context,
     request: Annotated[
         dict[str, Any],
-        typer.Option(click_type=REQUEST_TYPE, help=_REQUEST_OPTION_HELP),
+        typer.Option(parser=_parse_request_parameter, help=_REQUEST_OPTION_HELP),
     ],
     yes: Annotated[
         bool,
@@ -995,11 +1024,11 @@ def collect_history(
     ],
     date_from: Annotated[
         datetime,
-        typer.Option(click_type=DATETIME_TYPE, help="Start date."),
+        typer.Option(parser=_parse_datetime_parameter, help="Start date."),
     ],
     date_to: Annotated[
         datetime,
-        typer.Option(click_type=DATETIME_TYPE, help="End date."),
+        typer.Option(parser=_parse_datetime_parameter, help="End date."),
     ],
     dataset: Annotated[
         list[Dataset] | None,
@@ -1016,14 +1045,14 @@ def collect_history(
     timeframe: Annotated[
         int,
         typer.Option(
-            click_type=TIMEFRAME_TYPE,
+            parser=_parse_timeframe_parameter,
             help="Rates timeframe (e.g., M1, H1, D1).",
         ),
     ] = 1,
     flags: Annotated[
         int,
         typer.Option(
-            click_type=TICK_FLAGS_TYPE,
+            parser=_parse_tick_flags_parameter,
             help="Tick copy flags (ALL, INFO, TRADE, or integer).",
         ),
     ] = "ALL",  # pyright: ignore[reportArgumentType]

{mt5cli-1.2.2 → mt5cli-1.2.3}/mt5cli/client.py

@@ -787,6 +787,31 @@ class _BaseMT5Client:
         """Return the last tick for a symbol."""
         return self._fetch(lambda c: c.symbol_info_tick_as_df(symbol=symbol))
 
+    def symbol_info_tick_as_dict(
+        self,
+        symbol: str,
+        *,
+        skip_to_datetime: bool = False,
+    ) -> dict[str, object]:
+        """Return the last tick as a plain mapping.
+
+        Args:
+            symbol: Symbol name.
+            skip_to_datetime: Preserve numeric MT5 time fields when ``True``.
+
+        Returns:
+            Tick fields using the underlying pdmt5 conversion behavior.
+        """
+        return self._fetch_value(
+            lambda c: cast(
+                "dict[str, object]",
+                c.symbol_info_tick_as_dict(
+                    symbol=symbol,
+                    skip_to_datetime=skip_to_datetime,
+                ),
+            )
+        )
+
     def market_book(self, symbol: str) -> pd.DataFrame:
         """Return market depth for a symbol."""
         return self._fetch(lambda c: c.market_book_get_as_df(symbol=symbol))

{mt5cli-1.2.2 → mt5cli-1.2.3}/mt5cli/trading.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import logging
 from dataclasses import asdict, dataclass
 from datetime import UTC, datetime
+from inspect import signature
 from math import floor, isfinite
 from numbers import Integral, Real
 from typing import TYPE_CHECKING, Literal, Protocol, TypedDict, cast
@@ -20,6 +21,7 @@ if TYPE_CHECKING:
     from typing import Any
 
 _logger = logging.getLogger(__name__)
+_DATETIME_TYPES = (datetime, pd.Timestamp)
 
 
 class _Mt5ClientProtocol(Protocol):
@@ -801,16 +803,57 @@ def get_tick_snapshot(
     client: _Mt5ClientProtocol,
     symbol: str,
 ) -> dict[str, float | int | None]:
-    """Return normalized latest tick data, including bid, ask, and timestamp."""
+    """Return normalized latest tick data with a numeric MT5 timestamp.
+
+    The numeric ``time`` preserves the original value returned by MT5 without
+    applying timezone or server-offset correction.
+    """
     method = getattr(client, "symbol_info_tick_as_dict", None)
-    value = (
-        method(symbol=symbol) if callable(method) else client.symbol_info_tick(symbol)
-    )
+    if callable(method):
+        try:
+            signature(method).bind(symbol=symbol, skip_to_datetime=True)
+        except (TypeError, ValueError):
+            value = method(symbol=symbol)
+        else:
+            value = method(symbol=symbol, skip_to_datetime=True)
+    else:
+        value = client.symbol_info_tick(symbol)
     snapshot = _snapshot_from_value(value, _TICK_SNAPSHOT_FIELDS)
     snapshot["symbol"] = snapshot.get("symbol") or symbol
+    snapshot["time"] = _numeric_tick_time(snapshot.get("time"))
     return cast("dict[str, float | int | None]", snapshot)
 
 
+def _numeric_tick_time(value: object) -> float | int | None:
+    """Normalize an MT5 timestamp to its numeric epoch representation.
+
+    Returns:
+        The numeric timestamp, or ``None`` for an unsupported value.
+    """
+    numeric: float | None
+    if value is None or isinstance(value, bool):
+        numeric = None
+    elif isinstance(value, _DATETIME_TYPES):
+        if pd.isna(value):
+            return None
+        timestamp = pd.Timestamp(value)
+        if timestamp.tzinfo is None:
+            timestamp = timestamp.tz_localize(UTC)
+        numeric = timestamp.timestamp()
+    elif isinstance(value, Integral):
+        return int(value)
+    elif isinstance(value, Real):
+        numeric = float(value)
+    elif isinstance(value, str):
+        try:
+            numeric = float(value)
+        except ValueError:
+            return None
+    else:
+        numeric = None
+    return numeric if numeric is not None and isfinite(numeric) else None
+
+
 _SERVER_CLOCK_OFFSET_ROUNDING_SECONDS = 1800.0
 _MAX_PLAUSIBLE_SERVER_CLOCK_OFFSET_SECONDS = 14 * 3600.0
 
@@ -821,12 +864,12 @@ def estimate_server_clock_offset_seconds(
 ) -> float | None:
     """Estimate the broker server clock offset from true UTC.
 
-    MT5 tick, bar, and deal timestamps are epoch values labeled in the
-    broker server's wall clock, which is commonly UTC+2 or UTC+3 rather
-    than true UTC. This reads the latest tick for ``symbol`` and compares
-    its timestamp to the current UTC time, rounding to the nearest half
-    hour: server offsets are whole or half-hour multiples, and rounding
-    absorbs a few minutes of real tick staleness.
+    MT5 documents copied tick and bar data as UTC, while the timezone contract
+    for ``symbol_info_tick()`` is not explicit. This helper reads the latest
+    tick for ``symbol`` to validate a suspected broker-specific clock offset
+    before downstream correction. It compares the tick timestamp to the
+    current UTC time and rounds to the nearest half hour, absorbing a few
+    minutes of real tick staleness.
 
     On a closed market, weekend, holiday, or illiquid symbol the latest tick
     can be hours or days old, in which case the tick-vs-now delta reflects

{mt5cli-1.2.2 → mt5cli-1.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mt5cli"
-version = "1.2.2"
+version = "1.2.3"
 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"}]
@@ -11,8 +11,8 @@ requires-python = ">= 3.11, < 3.14"
 dependencies = [
   "pdmt5 >= 1.2.0",
   "pandas >= 2.2.2",
-  "click >= 8.1.0",
-  "typer >= 0.15.0",
+  "click >= 8.4",
+  "typer >= 0.26.0",
 ]
 classifiers = [
   "Development Status :: 3 - Alpha",

{mt5cli-1.2.2 → mt5cli-1.2.3}/tests/test_cli.py

@@ -25,6 +25,10 @@ from mt5cli.cli import (
     TIMEFRAME_TYPE,  # type: ignore[reportPrivateUsage]
     _execute_export,  # type: ignore[reportPrivateUsage]
     _ExportContext,  # type: ignore[reportPrivateUsage]
+    _parse_datetime_parameter,  # type: ignore[reportPrivateUsage]
+    _parse_request_parameter,  # type: ignore[reportPrivateUsage]
+    _parse_tick_flags_parameter,  # type: ignore[reportPrivateUsage]
+    _parse_timeframe_parameter,  # type: ignore[reportPrivateUsage]
     _sdk_client,  # type: ignore[reportPrivateUsage]
     app,
     main,
@@ -2195,6 +2199,11 @@ class TestDateTimeType:
         with pytest.raises(Exception, match="Invalid datetime"):
             DATETIME_TYPE.convert("bad", None, None)
 
+    def test_parser_invalid(self) -> None:
+        """Test that Typer receives a BadParameter with validation details."""
+        with pytest.raises(Exception, match="Invalid datetime"):
+            _parse_datetime_parameter("bad")
+
 
 class TestTimeframeType:
     """Tests for _TimeframeType."""
@@ -2224,6 +2233,11 @@ class TestTimeframeType:
         with pytest.raises(Exception, match="Invalid timeframe"):
             TIMEFRAME_TYPE.convert(value, None, None)
 
+    def test_parser_invalid(self) -> None:
+        """Test that Typer receives a BadParameter with validation details."""
+        with pytest.raises(Exception, match="Invalid timeframe"):
+            _parse_timeframe_parameter("bad")
+
 
 class TestTickFlagsType:
     """Tests for _TickFlagsType."""
@@ -2253,6 +2267,11 @@ class TestTickFlagsType:
         with pytest.raises(Exception, match="Invalid tick flags"):
             TICK_FLAGS_TYPE.convert(value, None, None)
 
+    def test_parser_invalid(self) -> None:
+        """Test that Typer receives a BadParameter with validation details."""
+        with pytest.raises(Exception, match="Invalid tick flags"):
+            _parse_tick_flags_parameter("bad")
+
 
 class TestRequestType:
     """Tests for _RequestType."""
@@ -2265,3 +2284,8 @@ class TestRequestType:
         """Test that invalid values raise BadParameter."""
         with pytest.raises(Exception, match="Invalid JSON request"):
             REQUEST_TYPE.convert("bad", None, None)
+
+    def test_parser_invalid(self) -> None:
+        """Test that Typer receives a BadParameter with validation details."""
+        with pytest.raises(Exception, match="Invalid JSON request"):
+            _parse_request_parameter("bad")

{mt5cli-1.2.2 → mt5cli-1.2.3}/tests/test_trading.py

@@ -15,6 +15,7 @@ from pdmt5 import Mt5RuntimeError
 from pytest_mock import MockerFixture  # noqa: TC002
 
 from mt5cli import trading
+from mt5cli.client import MT5Client
 from mt5cli.exceptions import Mt5OperationError
 from mt5cli.trading import (
     MarginVolume,
@@ -671,6 +672,99 @@ class TestSnapshotsAndState:
         assert get_symbol_snapshot(client, "EURUSD")["symbol"] == "EURUSD"
         assert get_tick_snapshot(client, "EURUSD")["symbol"] == "EURUSD"
 
+    def test_tick_snapshot_requests_raw_time_from_mt5_client(self) -> None:
+        """Test the canonical client preserves pdmt5's numeric MT5 time."""
+
+        class ConnectedClient:
+            def symbol_info_tick_as_dict(
+                self,
+                symbol: str,
+                skip_to_datetime: bool = False,
+            ) -> dict[str, float]:
+                assert symbol == "USOIL"
+                assert skip_to_datetime is True
+                return {"time": 1717250400, "bid": 78.5, "ask": 78.6}
+
+        client = MT5Client.from_connected_client(ConnectedClient())
+
+        snapshot = get_tick_snapshot(client, "USOIL")
+
+        assert snapshot["time"] == 1717250400
+        _assert_close(snapshot["bid"], 78.5)
+        _assert_close(snapshot["ask"], 78.6)
+
+    def test_tick_snapshot_supports_dict_method_without_skip_keyword(self) -> None:
+        """Test compatible dictionary clients need not accept pdmt5 options."""
+
+        class DictionaryClient:
+            def symbol_info_tick_as_dict(self, *, symbol: str) -> dict[str, float]:
+                assert symbol == "UKOIL"
+                return {"time": 1717254000, "bid": 80.1, "ask": 80.2}
+
+        snapshot = get_tick_snapshot(
+            cast("_Mt5ClientProtocol", DictionaryClient()),
+            "UKOIL",
+        )
+
+        assert snapshot["time"] == 1717254000
+
+    @pytest.mark.parametrize(
+        "tick_time",
+        [
+            pd.Timestamp("2024-06-01 15:00:00"),
+            pd.Timestamp("2024-06-01 15:00:00", tz=UTC),
+        ],
+        ids=["naive", "timezone-aware"],
+    )
+    def test_tick_snapshot_normalizes_dataframe_timestamp_to_numeric(
+        self,
+        tick_time: pd.Timestamp,
+    ) -> None:
+        """Test DataFrame fallbacks cannot leak a naive pandas Timestamp."""
+        client = MagicMock()
+        del client.symbol_info_tick_as_dict
+        client.symbol_info_tick.return_value = pd.DataFrame(
+            [{"time": tick_time, "bid": 1.0}],
+        )
+
+        snapshot = get_tick_snapshot(client, "EURUSD")
+
+        _assert_close(snapshot["time"], 1717254000.0)
+        assert not isinstance(snapshot["time"], pd.Timestamp)
+
+    @pytest.mark.parametrize(
+        ("tick_time", "expected"),
+        [
+            (True, None),
+            (float("inf"), None),
+            (pd.NaT, None),
+            ("1717254000", 1717254000.0),
+            (object(), None),
+        ],
+        ids=[
+            "boolean",
+            "non-finite",
+            "missing-datetime",
+            "numeric-string",
+            "unsupported",
+        ],
+    )
+    def test_tick_snapshot_time_always_matches_numeric_contract(
+        self,
+        tick_time: object,
+        expected: float | None,
+    ) -> None:
+        """Test non-canonical time payloads normalize to a number or None."""
+        client = MagicMock()
+        client.symbol_info_tick_as_dict.return_value = {"time": tick_time}
+
+        snapshot = get_tick_snapshot(client, "EURUSD")
+
+        if expected is None:
+            assert snapshot["time"] is None
+        else:
+            _assert_close(snapshot["time"], expected)
+
     def test_symbol_and_tick_snapshots_use_object_fallbacks(self) -> None:
         """Test symbol and tick snapshots support non-dict MT5 values."""
         client = MagicMock()
@@ -3983,19 +4077,21 @@ class TestEstimateServerClockOffsetSeconds:
         client.symbol_info_tick_as_dict.return_value = {"time": tick_time}
         return client
 
-    def test_rounds_positive_offset_to_nearest_half_hour(
+    @pytest.mark.parametrize("server_offset", [7200.0, 10800.0])
+    def test_rounds_positive_broker_offset_to_nearest_half_hour(
         self,
         mocker: MockerFixture,
+        server_offset: float,
     ) -> None:
-        """A tick ~3h ahead of UTC now estimates a rounded +3h offset."""
+        """UTC+2 and UTC+3 broker tick labels yield their server offsets."""
         frozen = datetime(2024, 6, 1, 12, 0, 0, tzinfo=UTC)
         mock_dt = mocker.patch("mt5cli.trading.datetime")
         mock_dt.now.return_value = frozen
-        client = self._client_with_tick_time(frozen.timestamp() + 10800.4)
+        client = self._client_with_tick_time(frozen.timestamp() + server_offset + 0.4)
 
         offset = estimate_server_clock_offset_seconds(client, "EURUSD")
 
-        _assert_close(offset, 10800.0)
+        _assert_close(offset, server_offset)
 
     def test_stale_tick_on_utc_server_rounds_to_zero(
         self,

{mt5cli-1.2.2 → mt5cli-1.2.3}/uv.lock

@@ -118,14 +118,14 @@ wheels = [
 
 [[package]]
 name = "click"
-version = "8.3.1"
+version = "8.4.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "colorama", marker = "sys_platform == 'win32'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/3d/fa/656b739db8587d7b5dfa22e22ed02566950fbfbcdc20311993483657a5c0/click-8.3.1.tar.gz", hash = "sha256:12ff4785d337a1bb490bb7e9c2b1ee5da3112e94a8622f26a6c77f5d2fc6842a", size = 295065, upload-time = "2025-11-15T20:45:42.706Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/76/d4/81420972a676e8ffea40450d8c8c92943e7218a78fe9b64359836cc9876b/click-8.4.2.tar.gz", hash = "sha256:9a6cea6e60b17ebe0a44c5cc636d94f09bd66142c1cd7d8b4cd731c4917a15f6", size = 338000, upload-time = "2026-06-24T17:45:15.148Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/98/78/01c019cdb5d6498122777c1a43056ebb3ebfeef2076d9d026bfe15583b2b/click-8.3.1-py3-none-any.whl", hash = "sha256:981153a64e25f12d547d3426c367a4857371575ee7ad18df2a6183ab0545b2a6", size = 108274, upload-time = "2025-11-15T20:45:41.139Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/e2/79c688af8b210d232694e31e59da9f6ec747bae31c3f5946e4e9b98860d5/click-8.4.2-py3-none-any.whl", hash = "sha256:e6f9f66136c816745b9d65817da91d61d957fb16e02e4dcd0552553c5a197b76", size = 119243, upload-time = "2026-06-24T17:45:13.73Z" },
 ]
 
 [[package]]
@@ -499,7 +499,7 @@ wheels = [
 
 [[package]]
 name = "mt5cli"
-version = "1.2.2"
+version = "1.2.3"
 source = { editable = "." }
 dependencies = [
     { name = "click" },
@@ -537,14 +537,14 @@ dev = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.1.0" },
+    { name = "click", specifier = ">=8.4" },
     { name = "opentelemetry-api", marker = "extra == 'otel'" },
     { name = "opentelemetry-exporter-otlp-proto-http", marker = "extra == 'otel'" },
     { name = "opentelemetry-sdk", marker = "extra == 'otel'" },
     { name = "pandas", specifier = ">=2.2.2" },
     { name = "pdmt5", specifier = ">=1.2.0" },
     { name = "pyarrow", marker = "extra == 'parquet'", specifier = ">=19.0.0" },
-    { name = "typer", specifier = ">=0.15.0" },
+    { name = "typer", specifier = ">=0.26.0" },
 ]
 provides-extras = ["parquet", "otel"]
 
@@ -1213,17 +1213,17 @@ wheels = [
 
 [[package]]
 name = "typer"
-version = "0.24.1"
+version = "0.26.8"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "annotated-doc" },
-    { name = "click" },
+    { name = "colorama", marker = "sys_platform == 'win32'" },
     { name = "rich" },
     { name = "shellingham" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/f5/24/cb09efec5cc954f7f9b930bf8279447d24618bb6758d4f6adf2574c41780/typer-0.24.1.tar.gz", hash = "sha256:e39b4732d65fbdcde189ae76cf7cd48aeae72919dea1fdfc16593be016256b45", size = 118613, upload-time = "2026-02-21T16:54:40.609Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/7c/f7/68adc395201b20b872d68e975386832e8005ffeacedd43a1d837a32815be/typer-0.26.8.tar.gz", hash = "sha256:c244a6bd558886fe3f8780efb6bdd28bb9aff005a94eedebaa5cb32926fe2f7e", size = 202097, upload-time = "2026-06-26T09:22:45.705Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/4a/91/48db081e7a63bb37284f9fbcefda7c44c277b18b0e13fbc36ea2335b71e6/typer-0.24.1-py3-none-any.whl", hash = "sha256:112c1f0ce578bfb4cab9ffdabc68f031416ebcc216536611ba21f04e9aa84c9e", size = 56085, upload-time = "2026-02-21T16:54:41.616Z" },
+    { url = "https://files.pythonhosted.org/packages/80/87/b9fd69c92c6102a066e1b86a35243f53e70bd4c709f2a26d9f4fee4f4dc0/typer-0.26.8-py3-none-any.whl", hash = "sha256:3512ca79ac5c11113414b36e80281b872884477722440691c89d1112e321a49c", size = 122564, upload-time = "2026-06-26T09:22:44.72Z" },
 ]
 
 [[package]]