mt5cli 0.8.2__tar.gz → 0.9.0__tar.gz

{mt5cli-0.8.2 → mt5cli-0.9.0}/.agents/skills/pr-feedback-triage/SKILL.md

@@ -27,7 +27,7 @@ If no PR or review comments are identifiable, ask for the target PR or the copie
 ## Modes
 
 - `dry_run`: inspect review feedback and report the triage only. Do not edit files, run write-mode formatters, commit, push, post replies, or resolve review threads.
-- `no_push`: local edits and verification are allowed, but do not push commits or otherwise update the remote branch. Report the local diff or local commits that still need to be pushed.
+- `no_push`: local edits and verification are allowed, but do not push commits or otherwise update the remote branch. Report the local diff or local commits that still need to be pushed. Do not resolve threads whose resolution depends on unpushed local edits.
 - `no_reply`: do not post replies, submit reviews, or resolve review threads. Provide suggested replies and resolution actions in the final report instead.
 
 When a mode disables an action, skip that destructive or externally visible action even if normal workflow text would otherwise allow it.
@@ -46,7 +46,7 @@ Gather the complete feedback set before editing:
 - Fetch unresolved review threads, requested-change reviews, PR-level summary comments, and copied comments.
 - Use platform-native APIs/CLI when available. Paginate results; do not inspect only the first page of threads or comments.
 - For bot reviewers that post both summary comments and inline comments, collect both. Summary comments often contain severity, rationale, and fix instructions; inline comments contain the exact file and line context.
-- Preserve each thread/comment identifier needed to reply or resolve later.
+- Preserve every thread/comment identifier needed to reply or resolve later.
 - Compare each comment with the current diff and file contents because review lines can become outdated.
 
 ## Deduplication and Ordering
@@ -60,7 +60,7 @@ Build one triage record per distinct finding:
 - Preserve the reviewer’s exact issue title and original wording where practical. Do not rename findings in a way that would make replies hard to map back to comments.
 - Preserve the reviewer’s original ordering unless the user asks for priority reordering. Many review bots already order findings by severity.
 
-Each triage record should track: original title, reviewer, source IDs, location, current applicability, severity/priority if available, disposition, planned action, verification, reply text if any, and resolution decision.
+Each triage record should track: original title, reviewer, source IDs, location, current applicability, severity/priority if available, disposition, planned action, verification, reply text if any, resolution decision, platform action attempted, and final platform state.
 
 ## Resolution Policy
 
@@ -70,6 +70,52 @@ Keep a thread open only when it still needs reviewer, maintainer, or product inp
 
 When resolving a thread, add a concise reply first only if it provides useful context, such as what changed, why no code change was needed, why a finding was intentionally deferred, or why the original comment is now outdated. Do not add noisy replies for self-evident fixes unless project norms require them.
 
+## Platform Action Contract
+
+Do not treat triage as complete until every collected source ID reaches an explicit terminal state:
+
+- `resolved`: a platform resolve action succeeded, or a re-check shows the thread is already resolved.
+- `replied_left_open`: a reply or question was posted and the thread is intentionally left unresolved.
+- `not_resolvable`: the source is a PR-level summary comment or copied comment that has no platform-level resolve action; reply or post a PR summary when useful.
+- `skipped_by_mode`: `dry_run`, `no_push`, or `no_reply` prevented the external action.
+- `failed_action`: a reply or resolve action was attempted and failed; include the attempted action and failure in the final summary.
+
+In normal mode, build and execute a platform action queue after fixes are verified and pushed when needed:
+
+- `reply_then_resolve`: use for handled threads where the reviewer needs context before resolution.
+- `resolve_only`: use for self-evident fixes and already-addressed or outdated threads where an extra reply would add noise.
+- `reply_leave_open`: use only for clarification requests, blocked work, or intentionally open follow-ups.
+- `reply_only`: use for PR-level comments or summaries that cannot be resolved as review threads.
+
+For duplicate findings, execute the terminal action for every source thread ID, not only the primary triage record. If one finding is represented by three unresolved inline threads, all three must be resolved or explicitly left open.
+
+## GitHub Action Guidance
+
+Prefer platform-native APIs or `gh` commands that expose review-thread resolution state. For GitHub inline review threads, use the thread node ID and the GraphQL `resolveReviewThread` mutation rather than assuming that a reply resolves the conversation.
+
+A reliable pattern is:
+
+1. Re-fetch review threads and comments immediately before acting.
+2. Reply to the thread when the action queue says a reply is needed.
+3. Resolve the review thread by node ID when the terminal state should be `resolved`.
+4. Re-fetch unresolved review threads after the action queue completes.
+5. Retry any expected-to-be-resolved thread that is still unresolved once; if it still remains unresolved, mark it `failed_action` instead of claiming completion.
+
+Example GraphQL mutation shape:
+
+```graphql
+mutation ($threadId: ID!) {
+  resolveReviewThread(input: { threadId: $threadId }) {
+    thread {
+      id
+      isResolved
+    }
+  }
+}
+```
+
+A posted reply alone is sufficient only for `reply_leave_open`, `reply_only`, or `not_resolvable` sources. For handled inline review threads, reply and resolve are separate actions.
+
 ## Flow
 
 ```mermaid
@@ -80,7 +126,7 @@ flowchart TD
   D --> E{Classify each triage record}
   E -->|Fix| F[Implement minimal change]
   E -->|Answer| G[Prepare concise reply]
-  E -->|Clarify| H[Leave open with question]
+  E -->|Clarify| H[Prepare question and leave open]
   E -->|Already addressed or Outdated| I[Prepare evidence]
   E -->|Defer or Won't fix| J[Document reason]
   F --> K[Verify]
@@ -92,11 +138,13 @@ flowchart TD
   L -->|dry_run| M[Report triage only]
   L -->|no_push| N[Report local diff or commits]
   L -->|no_reply| O[Report suggested replies/actions]
-  L -->|normal| P[Commit/push if changed, then batch reply and resolve handled threads]
+  L -->|normal| P[Commit/push if changed]
+  P --> R[Execute reply/resolve action queue]
+  R --> S[Re-fetch threads and retry unresolved handled threads once]
   M --> Q[Final summary]
   N --> Q
   O --> Q
-  P --> Q
+  S --> Q
 ```
 
 ## Compact Workflow
@@ -109,7 +157,7 @@ flowchart TD
 2. **Classify each triage record**
    - **Fix**: Valid requested change; make the smallest focused edit when not in `dry_run`.
    - **Answer**: No code change needed; prepare a concise explanation.
-   - **Clarify**: Ambiguous, conflicting, or missing context; leave open with a question.
+   - **Clarify**: Ambiguous, conflicting, or missing context; reply with the question and leave unresolved.
    - **Already addressed**: Current code already satisfies it; prepare evidence.
    - **Outdated**: Commented code or issue no longer exists; prepare evidence.
    - **Defer / Won't fix**: Valid concern intentionally not changed now; document a specific reason.
@@ -118,17 +166,19 @@ flowchart TD
    - Keep edits scoped to the review feedback.
    - Follow reviewer-provided fix instructions literally when they are still applicable; deviate only when the current code proves the instruction is stale or unsafe.
    - In `dry_run`, stop at triage, proposed fixes, suggested replies, and verification plan.
-   - In `no_push`, local edits are allowed, but do not push or resolve threads for local-only fixes.
+   - In `no_push`, local edits are allowed, but do not push or resolve threads whose fix is only local. Reply or resolve non-code, already-addressed, or outdated threads only when the action does not depend on unpushed work and `no_reply` is not set.
    - In `no_reply`, do not post replies or resolve threads; report suggested replies/actions instead.
-   - In normal mode, batch replies where practical, then resolve every handled thread by default after the fix, explanation, or deferral reason is available on the PR.
+   - In normal mode, commit and push changed code when appropriate, then execute the platform action queue for every collected source ID.
 
 4. **Verify before claiming completion**
    - For fixes, run appropriate checks or explain why they could not run.
    - Re-inspect the updated diff and comment context to confirm the concern is resolved.
+   - Re-fetch review threads after reply/resolve actions and confirm all expected-to-be-resolved thread IDs are resolved.
    - Do not mark a thread resolved if it still needs reviewer, maintainer, or product input.
+   - If a resolve or reply operation fails, retry once when safe; then report `failed_action` with the affected source ID and reason.
 
 5. **Finish**
-   - Normal mode: commit/push changes when appropriate, post useful replies or a summary, and resolve all handled threads by default.
+   - Normal mode: commit/push changes when appropriate, post useful replies or a summary, resolve all handled threads by default, and reconcile the final unresolved set.
    - Safe modes: report the local state and the exact replies/resolution actions a human could take.
 
 ## Reply Guidance
@@ -143,7 +193,9 @@ flowchart TD
 
 - Mode used: `normal`, `dry_run`, `no_push`, or `no_reply`
 - Counts by disposition: fixed, answered, clarified/left open, already addressed, outdated, deferred/won't-fix
-- Threads resolved, intentionally left open, or resolution actions skipped by mode
+- Counts by platform terminal state: resolved, replied-left-open, not-resolvable, skipped-by-mode, failed-action
+- Threads resolved, intentionally left open, already resolved, or resolution actions skipped by mode
+- Any expected-to-be-resolved thread that remained unresolved after retry
 - Verification run or planned
 - Commits pushed, local diff/commits, or "none"
 - Remaining open items and who needs to respond

{mt5cli-0.8.2 → mt5cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mt5cli
-Version: 0.8.2
+Version: 0.9.0
 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.2 → mt5cli-0.9.0}/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,14 +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 |
-| `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
 
@@ -96,6 +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 |
 | `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.2 → mt5cli-0.9.0}/docs/api/sdk.md

@@ -31,9 +31,10 @@ rates = collect_latest_rates_for_accounts_with_retries(
 ### Latest closed rate bars
 
 MetaTrader 5 `start_pos=0` includes the still-forming current bar as the last
-row. `fetch_latest_closed_rates()` handles one connected client; multi-account
-helpers fetch `count + 1` bars, drop that row with `drop_forming_rate_bar()`,
-and validate each series is non-empty. Returned frames are ordered
+row. `fetch_latest_closed_rates()` handles one connected `Mt5CliClient`; use
+`fetch_latest_closed_rates_for_trading_client()` from an active
+`Mt5TradingClient` session. Multi-account helpers fetch `count + 1` bars, drop
+that row with `drop_forming_rate_bar()`, and validate each series is non-empty. Returned frames are ordered
 oldest-to-newest and may contain fewer than `count` rows only when MT5 returns
 fewer closed bars.
 
@@ -85,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.2 → mt5cli-0.9.0}/docs/api/trading.md

@@ -40,15 +40,20 @@ betting logic, or scheduling code in downstream applications.
 
 ```python
 from mt5cli import (
+    calculate_positions_margin,
     calculate_spread_ratio,
     calculate_margin_and_volume,
     close_open_positions,
     detect_position_side,
     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,
     get_tick_snapshot,
+    normalize_order_volume,
     place_market_order,
 )
 
@@ -58,6 +63,30 @@ tick = get_tick_snapshot(client, "EURUSD")
 positions = get_positions_frame(client, "EURUSD")
 side = detect_position_side(client, "EURUSD")
 spread_ratio = calculate_spread_ratio(client, "EURUSD")
+volume = normalize_order_volume(
+    0.15,
+    volume_min=symbol["volume_min"],
+    volume_max=symbol["volume_max"],
+    volume_step=symbol["volume_step"],
+)
+buy_margin = (
+    estimate_order_margin(client, "EURUSD", "BUY", volume) if volume > 0 else 0.0
+)
+open_margin = calculate_positions_margin(client, symbols=["EURUSD"])
+closed_bars = fetch_latest_closed_rates_for_trading_client(
+    client,
+    symbol="EURUSD",
+    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",
@@ -87,6 +116,12 @@ closed = close_open_positions(client, symbols="EURUSD", dry_run=True)
 sell-only exposure, and `None` for no positions or mixed long/short exposure.
 `calculate_spread_ratio()` uses `(ask - bid) / ((ask + bid) / 2)` and raises
 `Mt5TradingError` when bid or ask is missing or non-positive.
+`normalize_order_volume()` returns `0.0` for invalid constraints or
+sub-minimum requests; check the result before calling `estimate_order_margin()`,
+which requires a positive finite volume. `calculate_positions_margin()` silently
+skips rows with missing symbols, non-positive volumes, non-finite volumes, or
+unsupported position types, but propagates `Mt5TradingError` from `estimate_order_margin()` when a valid row
+encounters invalid tick data or margin results from the broker.
 
 SL/TP ratios for `determine_order_limits()` must satisfy `0 <= ratio < 1`; `0`
 omits that level. SL/TP prices are rounded with symbol `digits` metadata when
@@ -148,13 +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 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.2 → mt5cli-0.9.0}/mt5cli/__init__.py

@@ -118,6 +118,7 @@ from .trading import (
     PositionSide,
     calculate_margin_and_volume,
     calculate_new_position_margin_ratio,
+    calculate_positions_margin,
     calculate_spread_ratio,
     calculate_volume_by_margin,
     close_open_positions,
@@ -125,11 +126,15 @@ from .trading import (
     detect_position_side,
     determine_order_limits,
     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,
     get_tick_snapshot,
     mt5_trading_session,
+    normalize_order_volume,
     place_market_order,
     update_sltp_for_open_positions,
 )
@@ -182,6 +187,7 @@ __all__ = [
     "build_rate_view_name",
     "calculate_margin_and_volume",
     "calculate_new_position_margin_ratio",
+    "calculate_positions_margin",
     "calculate_spread_ratio",
     "calculate_volume_by_margin",
     "call_with_normalized_errors",
@@ -204,9 +210,12 @@ __all__ = [
     "drop_forming_rate_bar",
     "ensure_symbol_selected",
     "ensure_utc",
+    "estimate_order_margin",
     "export_dataframe",
     "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",
@@ -230,6 +239,7 @@ __all__ = [
     "mt5_version",
     "normalize_dataframe",
     "normalize_mt5_exception",
+    "normalize_order_volume",
     "normalize_symbol",
     "normalize_symbols",
     "normalize_time_columns",

{mt5cli-0.8.2 → mt5cli-0.9.0}/mt5cli/contract.py

@@ -30,6 +30,7 @@ STABLE_SDK_EXPORTS: frozenset[str] = frozenset({
     "build_rate_view_name",
     "calculate_margin_and_volume",
     "calculate_new_position_margin_ratio",
+    "calculate_positions_margin",
     "calculate_spread_ratio",
     "calculate_volume_by_margin",
     "call_with_normalized_errors",
@@ -50,9 +51,12 @@ STABLE_SDK_EXPORTS: frozenset[str] = frozenset({
     "determine_order_limits",
     "drop_forming_rate_bar",
     "ensure_symbol_selected",
+    "estimate_order_margin",
     "export_dataframe",
     "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",
@@ -74,6 +78,7 @@ STABLE_SDK_EXPORTS: frozenset[str] = frozenset({
     "mt5_trading_session",
     "mt5_version",
     "normalize_mt5_exception",
+    "normalize_order_volume",
     "orders",
     "place_market_order",
     "positions",

{mt5cli-0.8.2 → mt5cli-0.9.0}/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
     ]