mt5cli 0.8.3__tar.gz → 0.9.1__tar.gz

{mt5cli-0.8.3 → mt5cli-0.9.1}/.agents/skills/pr-feedback-triage/SKILL.md

@@ -104,8 +104,8 @@ A reliable pattern is:
 Example GraphQL mutation shape:
 
 ```graphql
-mutation($threadId: ID!) {
-  resolveReviewThread(input: {threadId: $threadId}) {
+mutation ($threadId: ID!) {
+  resolveReviewThread(input: { threadId: $threadId }) {
     thread {
       id
       isResolved

{mt5cli-0.8.3 → mt5cli-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mt5cli
-Version: 0.8.3
+Version: 0.9.1
 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-0.8.3 → mt5cli-0.9.1}/docs/api/public-contract.md

@@ -19,20 +19,27 @@ alias for new code.
 
 ### Session lifecycle and configuration
 
-| Symbol                                          | Role                                                             |
-| ----------------------------------------------- | ---------------------------------------------------------------- |
-| `MT5Client`, `Mt5CliClient`                     | Read-only data client with optional `order_check` / `order_send` |
-| `build_config`                                  | Build `pdmt5.Mt5Config` from connection fields                   |
-| `mt5_session`                                   | Context manager: initialize, login, yield client, shutdown       |
-| `create_trading_client`, `mt5_trading_session`  | Trading-capable `pdmt5.Mt5TradingClient` lifecycle               |
-| `AccountSpec`                                   | Generic account group: symbols plus optional credentials         |
-| `resolve_account_spec`, `resolve_account_specs` | Merge overrides and expand `${ENV_VAR}` placeholders             |
-| `substitute_env_placeholders`                   | Replace `${NAME}` substrings from the environment                |
+| Symbol                                          | Role                                                                                                       |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `MT5Client`, `Mt5CliClient`                     | Read-only data client with optional `order_check` / `order_send`                                           |
+| `build_config`                                  | Build `pdmt5.Mt5Config` from connection fields                                                             |
+| `mt5_session`                                   | Context manager: initialize, login, yield client, shutdown                                                 |
+| `create_trading_client`, `mt5_trading_session`  | Trading-capable `pdmt5.Mt5TradingClient` lifecycle                                                         |
+| `AccountSpec`                                   | Generic account group: symbols plus optional credentials                                                   |
+| `resolve_account_spec`, `resolve_account_specs` | Merge overrides and expand `${ENV_VAR}` placeholders; opt-in `allow_whole_dollar_env` for bare `$NAME`     |
+| `substitute_env_placeholders`                   | Replace `${NAME}` substrings from the environment; opt-in `allow_whole_dollar_env` for whole-value `$NAME` |
 
 Credential resolution is generic: any environment variable name may appear inside
 `${...}`. mt5cli does not hard-code application-specific keys such as
 `mt5_login` or `mt5_exe`.
 
+Pass `allow_whole_dollar_env=True` to `substitute_env_placeholders()`,
+`resolve_account_spec()`, `resolve_account_specs()`, and `build_config()` to
+additionally expand strings whose entire value is a bare `$ENV_NAME` identifier.
+Partial strings such as `"plan$pass"`, `"abc$ENV"`, or `"$ENV-suffix"` are
+**never** expanded — only an exact `$IDENTIFIER` whole-string match qualifies.
+Default is `False` to preserve backward compatibility.
+
 ### Read-only MT5 data access
 
 Module-level helpers open a transient connection per call. Prefer `mt5_session`
@@ -56,15 +63,16 @@ MetaTrader 5 returns the still-forming bar as the last row when
 `start_pos=0`. Use these helpers instead of reimplementing bar trimming or
 timestamp normalization in downstream apps.
 
-| Symbol                                           | Role                                                         |
-| ------------------------------------------------ | ------------------------------------------------------------ |
-| `drop_forming_rate_bar`                          | Remove the last row from chronologically ordered rate data   |
-| `fetch_latest_closed_rates`                      | Single connected client: fetch `count + 1`, drop forming bar |
-| `fetch_latest_closed_rates_for_trading_client`   | Closed bars from an active `Mt5TradingClient` session        |
-| `collect_latest_closed_rates_for_accounts`       | Multi-account closed bars with optional retry wrapper        |
-| `collect_latest_closed_rates_by_granularity`     | Same data keyed by `(symbol, granularity_name)`              |
-| `collect_latest_rates_for_accounts`              | Latest bars including the forming bar when `start_pos=0`     |
-| `collect_latest_rates_for_accounts_with_retries` | Bounded exponential backoff for transient MT5 errors         |
+| Symbol                                           | Role                                                                            |
+| ------------------------------------------------ | ------------------------------------------------------------------------------- |
+| `drop_forming_rate_bar`                          | Remove the last row from chronologically ordered rate data                      |
+| `fetch_latest_closed_rates`                      | Single connected client: fetch `count + 1`, drop forming bar                    |
+| `fetch_latest_closed_rates_for_trading_client`   | Closed bars from an active `Mt5TradingClient` session; returns RangeIndex       |
+| `fetch_latest_closed_rates_indexed`              | Same as above but returns a UTC `DatetimeIndex` named `"time"` (no time column) |
+| `collect_latest_closed_rates_for_accounts`       | Multi-account closed bars with optional retry wrapper                           |
+| `collect_latest_closed_rates_by_granularity`     | Same data keyed by `(symbol, granularity_name)`                                 |
+| `collect_latest_rates_for_accounts`              | Latest bars including the forming bar when `start_pos=0`                        |
+| `collect_latest_rates_for_accounts_with_retries` | Bounded exponential backoff for transient MT5 errors                            |
 
 ### SQLite history collection and rate loading
 
@@ -97,7 +105,7 @@ strategy entries, exits, Kelly sizing, or signal logic.
 | `detect_position_side`                                                                             | Net long / short / flat from open positions   |
 | `calculate_spread_ratio`                                                                           | Relative bid-ask spread                       |
 | `calculate_margin_and_volume`, `calculate_volume_by_margin`, `calculate_new_position_margin_ratio` | Margin budget and volume sizing               |
-| `normalize_order_volume`, `estimate_order_margin`, `calculate_positions_margin`                      | Broker volume normalization and margin totals |
+| `normalize_order_volume`, `estimate_order_margin`, `calculate_positions_margin`                    | Broker volume normalization and margin totals |
 | `determine_order_limits`                                                                           | SL/TP price levels from ratios                |
 | `ensure_symbol_selected`                                                                           | Select/verify Market Watch visibility         |
 | `place_market_order`, `close_open_positions`, `update_sltp_for_open_positions`                     | Order execution helpers (`dry_run` supported) |

{mt5cli-0.8.3 → mt5cli-0.9.1}/docs/api/sdk.md

@@ -86,6 +86,28 @@ resolved = resolve_account_specs(accounts, server="Broker-Demo")
 # resolved[0].login == "12345", resolved[0].server == "Broker-Demo"
 ```
 
+Pass `allow_whole_dollar_env=True` to also expand strings whose **entire value**
+is a bare `$ENV_NAME` identifier (no braces). This opt-in covers
+`substitute_env_placeholders()`, `resolve_account_spec()`,
+`resolve_account_specs()`, and `build_config()`. Note: `build_config` cannot
+expand `login` because that parameter is `int | None`; use
+`resolve_account_spec` for a string `login` placeholder. Partial strings such as
+`"plan$pass"`, `"abc$ENV"`, or `"$ENV-suffix"` are never expanded — only an
+exact `$IDENTIFIER` whole-string match qualifies. The default is `False` to
+preserve backward compatibility.
+
+```python
+import os
+
+from mt5cli import AccountSpec, resolve_account_specs
+
+os.environ["MT5_PASSWORD"] = "secret"
+accounts = [AccountSpec(symbols=["EURUSD"], password="$MT5_PASSWORD")]
+
+resolved = resolve_account_specs(accounts, allow_whole_dollar_env=True)
+# resolved[0].password == "secret"
+```
+
 ### Throttled incremental history updates
 
 `ThrottledHistoryUpdater` wraps `update_history()` with a minimum interval

{mt5cli-0.8.3 → mt5cli-0.9.1}/docs/api/trading.md

@@ -48,6 +48,7 @@ from mt5cli import (
     determine_order_limits,
     estimate_order_margin,
     fetch_latest_closed_rates_for_trading_client,
+    fetch_latest_closed_rates_indexed,
     get_account_snapshot,
     get_positions_frame,
     get_symbol_snapshot,
@@ -78,6 +79,14 @@ closed_bars = fetch_latest_closed_rates_for_trading_client(
     granularity="M1",
     count=100,
 )
+# Or fetch with a UTC DatetimeIndex instead of a "time" column:
+indexed_bars = fetch_latest_closed_rates_indexed(
+    client,
+    symbol="EURUSD",
+    granularity="M1",
+    count=100,
+)
+# indexed_bars.index is a UTC-aware DatetimeIndex named "time"
 sizing = calculate_margin_and_volume(
     client,
     "EURUSD",
@@ -174,16 +183,16 @@ through the stable package root without embedding entry/exit policy.
 
 ## Migration from application-local helpers
 
-| Application-local concern                                | mt5cli replacement                              |
-| -------------------------------------------------------- | ----------------------------------------------- |
-| Manual terminal spawn/kill around trading code           | `mt5_trading_session()`                         |
-| Local position-side detection                            | `detect_position_side()`                        |
-| Local margin/volume sizing                               | `calculate_margin_and_volume()`                 |
-| Local broker volume step normalization                   | `normalize_order_volume()`                      |
-| Local order or position margin estimation                | `estimate_order_margin()`, `calculate_positions_margin()` |
-| Local closed-bar fetch from a trading session            | `fetch_latest_closed_rates_for_trading_client()` |
-| Local SL/TP price derivation                             | `determine_order_limits()`                      |
-| Throttled SQLite history loop with ad-hoc error handling | `ThrottledHistoryUpdater(suppress_errors=True)` |
+| Application-local concern                                | mt5cli replacement                                                                      |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| Manual terminal spawn/kill around trading code           | `mt5_trading_session()`                                                                 |
+| Local position-side detection                            | `detect_position_side()`                                                                |
+| Local margin/volume sizing                               | `calculate_margin_and_volume()`                                                         |
+| Local broker volume step normalization                   | `normalize_order_volume()`                                                              |
+| Local order or position margin estimation                | `estimate_order_margin()`, `calculate_positions_margin()`                               |
+| Local closed-bar fetch from a trading session            | `fetch_latest_closed_rates_for_trading_client()`, `fetch_latest_closed_rates_indexed()` |
+| Local SL/TP price derivation                             | `determine_order_limits()`                                                              |
+| Throttled SQLite history loop with ad-hoc error handling | `ThrottledHistoryUpdater(suppress_errors=True)`                                         |
 
 Keep read-only data collection on `mt5_session()` / `Mt5CliClient`; use
 `mt5_trading_session()` only where order placement or trading calculations are

{mt5cli-0.8.3 → mt5cli-0.9.1}/mt5cli/__init__.py

@@ -128,6 +128,7 @@ from .trading import (
     ensure_symbol_selected,
     estimate_order_margin,
     fetch_latest_closed_rates_for_trading_client,
+    fetch_latest_closed_rates_indexed,
     get_account_snapshot,
     get_positions_frame,
     get_symbol_snapshot,
@@ -214,6 +215,7 @@ __all__ = [
     "export_dataframe_to_sqlite",
     "fetch_latest_closed_rates",
     "fetch_latest_closed_rates_for_trading_client",
+    "fetch_latest_closed_rates_indexed",
     "get_account_snapshot",
     "get_positions_frame",
     "get_symbol_snapshot",

{mt5cli-0.8.3 → mt5cli-0.9.1}/mt5cli/contract.py

@@ -56,6 +56,7 @@ STABLE_SDK_EXPORTS: frozenset[str] = frozenset({
     "export_dataframe_to_sqlite",
     "fetch_latest_closed_rates",
     "fetch_latest_closed_rates_for_trading_client",
+    "fetch_latest_closed_rates_indexed",
     "get_account_snapshot",
     "get_positions_frame",
     "get_symbol_snapshot",

{mt5cli-0.8.3 → mt5cli-0.9.1}/mt5cli/sdk.py

@@ -309,12 +309,33 @@ def build_config(
     password: str | None = None,
     server: str | None = None,
     timeout: int | None = None,
+    allow_whole_dollar_env: bool = False,
 ) -> Mt5Config:
     """Build an ``Mt5Config`` from optional connection parameters.
 
+    Args:
+        path: Optional terminal executable path.
+        login: Optional trading account login.
+        password: Optional trading account password.
+        server: Optional trading server name.
+        timeout: Optional connection timeout in milliseconds.
+        allow_whole_dollar_env: When ``True``, string parameters that are
+            exactly ``$ENV_NAME`` are expanded from the environment. Applies
+            to ``path``, ``password``, and ``server``. Default ``False``
+            preserves existing behavior.
+
     Returns:
         Configured ``Mt5Config`` instance.
     """
+    if allow_whole_dollar_env:
+        if path is not None:
+            path = substitute_env_placeholders(path, allow_whole_dollar_env=True)
+        if password is not None:
+            password = substitute_env_placeholders(
+                password, allow_whole_dollar_env=True
+            )
+        if server is not None:
+            server = substitute_env_placeholders(server, allow_whole_dollar_env=True)
     return Mt5Config(
         path=path,
         login=login,
@@ -1376,13 +1397,22 @@ class AccountSpec:
 
 
 _ENV_PLACEHOLDER_PATTERN = re.compile(r"\$\{(?P<name>[A-Za-z_][A-Za-z0-9_]*)\}")
+_WHOLE_DOLLAR_PATTERN = re.compile(r"^\$(?P<name>[A-Za-z_][A-Za-z0-9_]*)$")
 
 
-def substitute_env_placeholders(value: str) -> str:
+def substitute_env_placeholders(
+    value: str,
+    *,
+    allow_whole_dollar_env: bool = False,
+) -> str:
     """Replace ``${ENV_VAR}`` placeholders in a string with environment values.
 
     Args:
         value: String that may contain one or more ``${ENV_VAR}`` placeholders.
+        allow_whole_dollar_env: When ``True``, a string that is exactly
+            ``$ENV_NAME`` (the whole value and nothing else) is also expanded
+            from the environment. Partial occurrences such as ``"plan$pass"``
+            or ``"$ENV-suffix"`` are left unchanged.
 
     Returns:
         The string with every placeholder replaced by its environment value.
@@ -1390,6 +1420,14 @@ def substitute_env_placeholders(value: str) -> str:
     Raises:
         ValueError: If a referenced environment variable is not set.
     """
+    if allow_whole_dollar_env:
+        m = _WHOLE_DOLLAR_PATTERN.match(value)
+        if m:
+            name = m.group("name")
+            if name not in os.environ:
+                msg = f"Environment variable {name!r} is not set."
+                raise ValueError(msg)
+            return os.environ[name]
     parts: list[str] = []
     last_end = 0
     for match in _ENV_PLACEHOLDER_PATTERN.finditer(value):
@@ -1404,7 +1442,12 @@ def substitute_env_placeholders(value: str) -> str:
     return "".join(parts)
 
 
-def _resolve_field(override: str | None, account_value: str | None) -> str | None:
+def _resolve_field(
+    override: str | None,
+    account_value: str | None,
+    *,
+    allow_whole_dollar_env: bool = False,
+) -> str | None:
     """Resolve a string field from an override or account value with env subst.
 
     Returns:
@@ -1414,12 +1457,16 @@ def _resolve_field(override: str | None, account_value: str | None) -> str | Non
     value = override if override is not None else account_value
     if value is None:
         return None
-    return substitute_env_placeholders(value)
+    return substitute_env_placeholders(
+        value, allow_whole_dollar_env=allow_whole_dollar_env
+    )
 
 
 def _resolve_login(
     override: int | str | None,
     account_login: int | str | None,
+    *,
+    allow_whole_dollar_env: bool = False,
 ) -> int | str | None:
     """Resolve a login from an override or account value with env substitution.
 
@@ -1431,10 +1478,14 @@ def _resolve_login(
     if override is not None:
         if isinstance(override, int):
             return override
-        return substitute_env_placeholders(override)
+        return substitute_env_placeholders(
+            override, allow_whole_dollar_env=allow_whole_dollar_env
+        )
     if account_login is None or isinstance(account_login, int):
         return account_login
-    return substitute_env_placeholders(account_login)
+    return substitute_env_placeholders(
+        account_login, allow_whole_dollar_env=allow_whole_dollar_env
+    )
 
 
 def resolve_account_spec(
@@ -1445,6 +1496,7 @@ def resolve_account_spec(
     server: str | None = None,
     path: str | None = None,
     timeout: int | None = None,
+    allow_whole_dollar_env: bool = False,
 ) -> AccountSpec:
     """Resolve an account's credentials from overrides and ``${ENV_VAR}`` values.
 
@@ -1460,6 +1512,9 @@ def resolve_account_spec(
         server: Optional explicit server override.
         path: Optional explicit terminal path override.
         timeout: Optional explicit connection timeout override.
+        allow_whole_dollar_env: When ``True``, string fields that are exactly
+            ``$ENV_NAME`` are also expanded from the environment. Default
+            ``False`` preserves existing behavior.
 
     Returns:
         A new :class:`AccountSpec` with resolved credentials and the original
@@ -1469,10 +1524,18 @@ def resolve_account_spec(
     """
     return AccountSpec(
         symbols=account.symbols,
-        login=_resolve_login(login, account.login),
-        password=_resolve_field(password, account.password),
-        server=_resolve_field(server, account.server),
-        path=_resolve_field(path, account.path),
+        login=_resolve_login(
+            login, account.login, allow_whole_dollar_env=allow_whole_dollar_env
+        ),
+        password=_resolve_field(
+            password, account.password, allow_whole_dollar_env=allow_whole_dollar_env
+        ),
+        server=_resolve_field(
+            server, account.server, allow_whole_dollar_env=allow_whole_dollar_env
+        ),
+        path=_resolve_field(
+            path, account.path, allow_whole_dollar_env=allow_whole_dollar_env
+        ),
         timeout=timeout if timeout is not None else account.timeout,
     )
 
@@ -1485,6 +1548,7 @@ def resolve_account_specs(
     server: str | None = None,
     path: str | None = None,
     timeout: int | None = None,
+    allow_whole_dollar_env: bool = False,
 ) -> list[AccountSpec]:
     """Resolve credentials for multiple accounts.
 
@@ -1498,6 +1562,9 @@ def resolve_account_specs(
         server: Optional explicit server override applied to each account.
         path: Optional explicit terminal path override applied to each account.
         timeout: Optional explicit timeout override applied to each account.
+        allow_whole_dollar_env: When ``True``, string fields that are exactly
+            ``$ENV_NAME`` are also expanded from the environment. Default
+            ``False`` preserves existing behavior.
 
     Returns:
         Resolved account specifications in the original order. Raises
@@ -1512,6 +1579,7 @@ def resolve_account_specs(
             server=server,
             path=path,
             timeout=timeout,
+            allow_whole_dollar_env=allow_whole_dollar_env,
         )
         for account in accounts
     ]

{mt5cli-0.8.3 → mt5cli-0.9.1}/mt5cli/trading.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from contextlib import contextmanager
 from math import floor, isfinite
-from numbers import Integral
+from numbers import Integral, Real
 from typing import TYPE_CHECKING, Literal, TypedDict, cast
 
 import pandas as pd
@@ -137,6 +137,7 @@ __all__ = [
     "ensure_symbol_selected",
     "estimate_order_margin",
     "fetch_latest_closed_rates_for_trading_client",
+    "fetch_latest_closed_rates_indexed",
     "get_account_snapshot",
     "get_positions_frame",
     "get_symbol_snapshot",
@@ -829,7 +830,9 @@ def calculate_volume_by_margin(
     """Calculate max normalized volume affordable for one side.
 
     Returns:
-        Affordable volume rounded down to symbol volume constraints.
+        Largest stepped volume whose actual margin (from ``order_calc_margin``)
+        fits within ``available_margin``, rounded down to symbol volume
+        constraints; ``0.0`` when no affordable step exists.
 
     Raises:
         Mt5TradingError: If symbol volume constraints or tick data are invalid.
@@ -844,8 +847,7 @@ def calculate_volume_by_margin(
         msg = f"Invalid volume constraints for {symbol!r}."
         raise Mt5TradingError(msg)
     side = _normalize_order_side(order_side)
-    tick = get_tick_snapshot(client, symbol)
-    price = tick["ask"] if side == "BUY" else tick["bid"]
+    price = get_tick_snapshot(client, symbol)["ask" if side == "BUY" else "bid"]
     if not isinstance(price, int | float) or price <= 0:
         msg = f"Tick price is unavailable for {symbol!r}."
         raise Mt5TradingError(msg)
@@ -855,11 +857,38 @@ def calculate_volume_by_margin(
     min_margin = float(client.order_calc_margin(order_type, symbol, volume_min, price))
     if min_margin <= 0 or min_margin > available_margin:
         return 0.0
-    raw_volume = available_margin / min_margin * volume_min
-    capped = min(raw_volume, volume_max) if volume_max > 0 else raw_volume
-    steps = floor(((capped - volume_min) / volume_step) + 1e-12)
-    normalized = volume_min + max(0, steps) * volume_step
-    return round(normalized, 10) if normalized >= volume_min else 0.0
+    lo = 0
+    hi = int(
+        max(
+            0,
+            floor(
+                (
+                    (
+                        min(available_margin / min_margin * volume_min, volume_max)
+                        if volume_max > 0
+                        else available_margin / min_margin * volume_min
+                    )
+                    - volume_min
+                )
+                / volume_step
+                + 1e-12
+            ),
+        )
+    )
+    best = -1
+
+    while lo <= hi:
+        mid = (lo + hi) // 2
+        normalized = round(volume_min + mid * volume_step, 10)
+        actual = float(client.order_calc_margin(order_type, symbol, normalized, price))
+
+        if actual > 0 and actual <= available_margin:
+            best = mid
+            lo = mid + 1
+        else:
+            hi = mid - 1
+
+    return round(volume_min + best * volume_step, 10) if best >= 0 else 0.0
 
 
 def determine_order_limits(
@@ -1202,6 +1231,92 @@ def fetch_latest_closed_rates_for_trading_client(
     return closed.tail(count).reset_index(drop=True)
 
 
+def _rate_time_to_utc(series: pd.Series, symbol: str) -> pd.DatetimeIndex:
+    """Convert a rate time series to a UTC-aware DatetimeIndex.
+
+    Handles MT5 epoch seconds (including object-dtype Python numbers), timezone-
+    naive datetime-like values, and timezone-aware datetime-like values.
+
+    Returns:
+        UTC-aware DatetimeIndex.
+
+    Raises:
+        ValueError: If the time data is invalid, unparseable, or contains NaT.
+    """
+    try:
+        arr = series.to_numpy()
+        non_null = series.dropna()
+        object_numbers = (
+            pd.api.types.is_object_dtype(series)
+            and non_null.map(
+                lambda value: type(value) is not bool and isinstance(value, Real),
+            ).all()
+        )
+        numeric_dtype = pd.api.types.is_numeric_dtype(
+            series
+        ) and not pd.api.types.is_bool_dtype(
+            series,
+        )
+        if numeric_dtype or object_numbers:
+            idx = pd.to_datetime(arr, unit="s", utc=True)
+        else:
+            idx = pd.to_datetime(arr, utc=True)
+    except Exception as exc:
+        msg = f"Rate data for {symbol!r} has invalid or unparseable time data."
+        raise ValueError(msg) from exc
+    if any(idx.isna()):
+        msg = f"Rate data for {symbol!r} contains missing (NaT) timestamp values."
+        raise ValueError(msg)
+    return idx
+
+
+def fetch_latest_closed_rates_indexed(
+    client: Mt5TradingClient,
+    *,
+    symbol: str,
+    granularity: str,
+    count: int,
+) -> pd.DataFrame:
+    """Fetch the latest closed bars with a UTC DatetimeIndex from a trading client.
+
+    Internally reuses :func:`fetch_latest_closed_rates_for_trading_client` for
+    closed-bar detection and validation, then converts the ``time`` column to a
+    UTC-aware :class:`~pandas.DatetimeIndex` named ``"time"`` and drops the
+    original column. Intended for downstream time-series consumers that require
+    a datetime index rather than a ``time`` column.
+
+    Args:
+        client: Connected trading client with rate-fetch capability.
+        symbol: Symbol name.
+        granularity: Timeframe string (for example ``"M1"``, ``"H1"``).
+        count: Maximum number of closed bars to return.
+
+    Returns:
+        Up to ``count`` closed bars ordered oldest to newest, with a
+        UTC-aware ``DatetimeIndex`` named ``"time"``. The original ``time``
+        column is dropped.
+
+    Raises:
+        ValueError: If ``count`` is not positive, rate data is empty or
+            malformed, the ``time`` column is missing, or timestamp data
+            is invalid or unparseable.
+    """
+    frame = fetch_latest_closed_rates_for_trading_client(
+        client,
+        symbol=symbol,
+        granularity=granularity,
+        count=count,
+    )
+    if "time" not in frame.columns:
+        msg = f"Rate data is missing a time column for {symbol!r}."
+        raise ValueError(msg)
+    idx = _rate_time_to_utc(frame["time"], symbol)
+    idx.name = "time"
+    result = frame.drop(columns=["time"])
+    result.index = idx
+    return result
+
+
 @contextmanager
 def mt5_trading_session(
     config: Mt5Config | None = None,

{mt5cli-0.8.3 → mt5cli-0.9.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mt5cli"
-version = "0.8.3"
+version = "0.9.1"
 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"}]
@@ -124,7 +124,6 @@ ignore = [
 ]
 
 [tool.ruff.lint.per-file-ignores]
-"mt5cli/history.py" = ["TC003"]
 "tests/**/*.py" = [
   "DOC201",   # Missing return documentation
   "DOC501",   # Raised exception missing from docstring

{mt5cli-0.8.3 → mt5cli-0.9.1}/tests/test_contracts.py

@@ -44,6 +44,7 @@ from mt5cli import (
     export_dataframe_to_sqlite,
     fetch_latest_closed_rates,
     fetch_latest_closed_rates_for_trading_client,
+    fetch_latest_closed_rates_indexed,
     granularity_name,
     is_recoverable_mt5_error,
     load_rate_data,
@@ -734,3 +735,32 @@ class TestStableSdkContract:
             raise RuntimeError(message)
 
         mock_client.shutdown.assert_called_once()
+
+    def test_fetch_latest_closed_rates_indexed_from_package_root(
+        self,
+        mocker: MockerFixture,
+    ) -> None:
+        """Indexed closed-bar helper returns a UTC DatetimeIndex named 'time'."""
+        client = MagicMock()
+        mocker.patch(
+            "mt5cli.trading.fetch_latest_closed_rates_for_trading_client",
+            return_value=pd.DataFrame(
+                {
+                    "time": [1704067200, 1704153600, 1704240000],
+                    "close": [1.0, 1.1, 1.2],
+                },
+            ),
+        )
+
+        result = fetch_latest_closed_rates_indexed(
+            client,
+            symbol="EURUSD",
+            granularity="M1",
+            count=2,
+        )
+
+        assert isinstance(result.index, pd.DatetimeIndex)
+        assert result.index.name == "time"
+        assert result.index.tz is not None
+        assert "time" not in result.columns
+        assert "close" in result.columns