Compare commits
14 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Daichi Narushima
|
dfe80ce500 | ||
|
Daichi Narushima
|
15bfd17db3 | ||
|
Daichi Narushima
|
37eef16e99 | ||
|
Daichi Narushima
|
96c75f7852 | ||
|
Daichi Narushima
|
292fac899a | ||
|
Daichi Narushima
|
9ac3b885c3 | ||
|
Daichi Narushima
|
823cb5b0a4 | ||
|
agent
|
1c57be5c44 | ||
|
Daichi Narushima
|
f1ada55bce | ||
|
agent
|
d292fbb9d9 | ||
|
Daichi Narushima
|
8e53212a24 | ||
|
Daichi Narushima
|
b878a61c07 | ||
|
dceoy
|
0610ea732c | ||
|
Daichi Narushima
|
82a39731ed |
@@ -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
|
||||
|
||||
@@ -31,7 +31,7 @@ pip install -U mt5cli MetaTrader5
|
||||
|
||||
## Python API (downstream packages)
|
||||
|
||||
Import `MT5Client` for generic MT5 data access, schema normalization, and optional order primitives. `Mt5CliClient` remains available as a backward-compatible alias.
|
||||
Import `MT5Client` for generic MT5 data access, schema normalization, and optional order primitives.
|
||||
|
||||
```python
|
||||
from datetime import UTC, datetime
|
||||
@@ -92,16 +92,21 @@ Schema contracts live in `mt5cli.schemas` (`DataKind`, `validate_schema`, `norma
|
||||
Trading applications can depend on `mt5cli` imports only; terminal path,
|
||||
credentials, server, and timeout are forwarded to `pdmt5.Mt5Config`, numeric
|
||||
login strings are coerced to integers, and empty login strings are treated as
|
||||
unset.
|
||||
unset. Pass `allow_whole_dollar_env=True` to expand `${ENV_VAR}` and bare
|
||||
`$ENV_NAME` placeholders in connection string parameters before coercion.
|
||||
|
||||
```python
|
||||
from mt5cli import (
|
||||
build_config,
|
||||
calculate_spread_ratio,
|
||||
create_trading_client,
|
||||
get_account_snapshot,
|
||||
mt5_trading_session,
|
||||
)
|
||||
|
||||
# Login from environment — numeric string is coerced to int automatically
|
||||
config = build_config(login="$MT5_LOGIN", allow_whole_dollar_env=True)
|
||||
|
||||
with mt5_trading_session(
|
||||
path=r"C:\Program Files\MetaTrader 5\terminal64.exe",
|
||||
login="12345",
|
||||
@@ -173,10 +178,13 @@ python -m mt5cli -o account.csv account-info
|
||||
| `recent-history-deals` | Export historical deals from a recent trailing window |
|
||||
| `mt5-summary` | Export terminal/account status summary |
|
||||
| `order-check` | Check funds sufficiency for a trade request |
|
||||
| `order-send` | Send a trade request to the trade server (`--yes` required) |
|
||||
| `order-send` | Send a raw trade request to the trade server (`--yes` required; expert path) |
|
||||
| `close-positions` | Close open positions by `--symbol` or `--ticket` (`--yes` required for live; `--dry-run` available) |
|
||||
| `collect-history` | Bundle rates, ticks, history-orders, and history-deals for one or more symbols into a single SQLite database |
|
||||
|
||||
Use `order-check` to validate a request payload before running `order-send --yes`.
|
||||
`close-positions` is the safer high-level alternative that builds correct close
|
||||
requests automatically. At least one `--symbol` or `--ticket` must be provided.
|
||||
|
||||
### `collect-history`
|
||||
|
||||
@@ -248,9 +256,9 @@ rates = collect_latest_closed_rates_by_granularity(
|
||||
eurusd_m1 = rates["EURUSD", "M1"] # closed bars only
|
||||
```
|
||||
|
||||
- **Credential resolution**: use `resolve_account_spec()` / `resolve_account_specs()` to merge explicit override values over `AccountSpec` fields and expand `${ENV_VAR}` placeholders (via `substitute_env_placeholders()`), raising `ValueError` for missing variables. This keeps secrets out of plan/config files without coupling to any strategy code.
|
||||
- **Credential resolution**: use `resolve_account_spec()` / `resolve_account_specs()` to merge explicit override values over `AccountSpec` fields and expand `${ENV_VAR}` placeholders (via `substitute_env_placeholders()`), raising `ValueError` for missing variables. This keeps secrets out of plan/config files without coupling to any strategy code. For config dicts or nested structures loaded from YAML/TOML, use `substitute_mapping_values(data, keys={"login", "password"})` to expand placeholders only for caller-specified keys — key names are never hard-coded in mt5cli.
|
||||
- **Throttled history updates**: use `ThrottledHistoryUpdater` to wrap `update_history()` with a minimum `interval_seconds` between successful runs (monotonic clock). Call `should_update()` / `update(client, symbols)` from an application loop; errors propagate by default, or pass `suppress_errors=True` to swallow recoverable `Mt5*Error`, `sqlite3.Error`, `ValueError`, `OSError`, and MT5 client capability errors for history API methods without advancing the throttle (other `AttributeError` / `TypeError` values always propagate). Pass `update_backend` to inject a custom history update callable (same keyword arguments as `update_history`) instead of monkey-patching `mt5cli.sdk.update_history`.
|
||||
- **Trading session helpers**: use `mt5_trading_session()` for a trading-capable `pdmt5.Mt5TradingClient` that initializes/logs in via `Mt5Config.path` and always shuts down safely. Pair with `detect_position_side()`, `calculate_margin_and_volume()`, and `determine_order_limits()` for generic position and sizing utilities. The read-only `mt5_session()` / `Mt5CliClient` SDK is unchanged.
|
||||
- **Trading session helpers**: use `mt5_trading_session()` for a trading-capable `pdmt5.Mt5TradingClient` that initializes/logs in via `Mt5Config.path` and always shuts down safely. Pair with `detect_position_side()`, `calculate_margin_and_volume()`, and `determine_order_limits()` for generic position and sizing utilities. Keep read-only collection on `mt5_session()` / `MT5Client`.
|
||||
- **Granularity-keyed rate loading**: `load_rate_series_by_granularity()` builds targets with `build_rate_targets()`, loads them with `load_rate_series_from_sqlite()`, and returns a mapping keyed by `(symbol | None, granularity_name)` such as `("EURUSD", "M1")` to reduce downstream boilerplate.
|
||||
- **MT5 session helper**: use the `mt5_session()` context manager to attach to (or, when `Mt5Config.path` is set, launch) an MT5 terminal, log in, and yield a connected `MT5Client` that shuts down on exit.
|
||||
- **SQLite export helpers**: use `export_dataframe_to_sqlite()` for append mode, optional index export, and post-write deduplication by key columns.
|
||||
@@ -317,7 +325,7 @@ finally:
|
||||
client.shutdown()
|
||||
```
|
||||
|
||||
Read-only collectors can keep using `mt5_session()` and `MT5Client` (or the `Mt5CliClient` alias) without changes.
|
||||
Read-only collectors can keep using `mt5_session()` and `MT5Client`.
|
||||
|
||||
## Development
|
||||
|
||||
|
||||
+112
-61
@@ -8,47 +8,48 @@ downstream app -> mt5cli -> pdmt5 -> MetaTrader 5
|
||||
```
|
||||
|
||||
Downstream packages should import from the package root (`from mt5cli import
|
||||
...`) and treat the symbols listed below as the stable SDK contract. CLI
|
||||
commands mirror the same behavior but are not importable Python APIs.
|
||||
...`) and use the public tier sets in `mt5cli.contract` to distinguish API
|
||||
stability. CLI commands mirror the same behavior but are not importable Python
|
||||
APIs.
|
||||
|
||||
## Public API tiers
|
||||
|
||||
mt5cli classifies package-root imports by intended downstream use:
|
||||
|
||||
| Tier | Contract set | Meaning |
|
||||
| ---------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Stable core | `STABLE_SDK_EXPORTS` | Preferred SDK surface for downstream MT5 infrastructure adapters. Changes require a deliberate compatibility path. |
|
||||
| Secondary public | `SECONDARY_PUBLIC_EXPORTS` | Public helpers for CLI/export/schema integrations and lower-level MT5 wrappers. Importable, but less central to the downstream trading SDK. |
|
||||
|
||||
## Stable downstream SDK API
|
||||
|
||||
These names are exported from `mt5cli` and covered by the contract in
|
||||
`mt5cli.STABLE_SDK_EXPORTS` (defined in `mt5cli.contract`). Prefer `MT5Client` over the legacy `Mt5CliClient`
|
||||
alias for new code.
|
||||
`mt5cli.STABLE_SDK_EXPORTS` (defined in `mt5cli.contract`).
|
||||
|
||||
### 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` | Read-only data client with optional `order_check` / `order_send` |
|
||||
| `build_config` | Build `pdmt5.Mt5Config` from connection fields; `login` accepts `int \| str \| None` — numeric strings are coerced to `int`, blank strings are treated as unset, and `${ENV_VAR}` / `$ENV_NAME` placeholders in string parameters are expanded when `allow_whole_dollar_env=True` |
|
||||
| `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` |
|
||||
| `substitute_mapping_values` | Recursively traverse a dict/list/scalar structure and substitute `${ENV_VAR}` placeholders for caller-selected mapping keys only; optionally normalise blank strings to `None` for a separate caller-selected key set; does not hard-code any application-specific key names |
|
||||
|
||||
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`.
|
||||
|
||||
### Read-only MT5 data access
|
||||
|
||||
Module-level helpers open a transient connection per call. Prefer `mt5_session`
|
||||
or `MT5Client` when making many requests in one process.
|
||||
|
||||
| Area | Symbols |
|
||||
| -------------------- | ---------------------------------------------------------------------------------------------------- |
|
||||
| Rates | `copy_rates_from`, `copy_rates_from_pos`, `copy_rates_range`, `latest_rates`, `collect_latest_rates` |
|
||||
| Ticks | `copy_ticks_from`, `copy_ticks_range`, `recent_ticks` |
|
||||
| Account / terminal | `account_info`, `terminal_info`, `mt5_version`, `last_error`, `mt5_summary`, `mt5_summary_as_df` |
|
||||
| Symbols / market | `symbols`, `symbol_info`, `symbol_info_tick`, `market_book`, `minimum_margins` |
|
||||
| Trading state (read) | `orders`, `positions`, `history_orders`, `history_deals`, `recent_history_deals` |
|
||||
|
||||
Use `mt5_version` for MetaTrader 5 terminal version data. The name `version` at
|
||||
the package root refers to `importlib.metadata.version` (package metadata), not
|
||||
the MT5 SDK helper.
|
||||
Pass `allow_whole_dollar_env=True` to `substitute_env_placeholders()`,
|
||||
`substitute_mapping_values()`, `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.
|
||||
|
||||
### Closed-bar rate helpers
|
||||
|
||||
@@ -56,15 +57,15 @@ 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_with_retries` | Bounded exponential backoff for transient MT5 errors |
|
||||
|
||||
### SQLite history collection and rate loading
|
||||
|
||||
@@ -91,18 +92,33 @@ diagrams.
|
||||
These helpers implement broker-facing calculations only. They do not encode
|
||||
strategy entries, exits, Kelly sizing, or signal logic.
|
||||
|
||||
| Symbol | Role |
|
||||
| -------------------------------------------------------------------------------------------------- | --------------------------------------------- |
|
||||
| `get_account_snapshot`, `get_symbol_snapshot`, `get_tick_snapshot`, `get_positions_frame` | Normalized account/symbol/tick/position views |
|
||||
| `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) |
|
||||
| `MarginVolume`, `OrderLimits`, `OrderExecutionResult` | Typed return contracts for order helpers |
|
||||
| `OrderSide`, `OrderFillingMode`, `OrderTimeMode`, `PositionSide`, `ExecutionStatus` | Typed enums for order helpers |
|
||||
| Symbol | Role |
|
||||
| ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
|
||||
| `get_account_snapshot`, `get_symbol_snapshot`, `get_tick_snapshot`, `get_positions_frame` | Normalized account/symbol/tick/position views |
|
||||
| `extract_tick_price` | Positive finite bid/ask extraction from tick mappings |
|
||||
| `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 |
|
||||
| `calculate_positions_margin_by_symbol` | Per-symbol margin map (resilient, first-seen order) |
|
||||
| `calculate_positions_margin_safe` | Summed total margin across symbols (failed symbols skipped) |
|
||||
| `calculate_projected_margin_ratio` | Estimated symbol-scoped margin/equity after optional new exposure |
|
||||
| `calculate_account_projected_margin_ratio` | Account snapshot margin/equity after optional new exposure |
|
||||
| `calculate_symbol_group_margin_ratio` | Estimated symbol-group margin/equity with optional exposure |
|
||||
| `determine_order_limits` | SL/TP price levels from ratios |
|
||||
| `calculate_trailing_stop_updates` | Per-ticket generic trailing stop-loss update plan |
|
||||
| `ensure_symbol_selected` | Select/verify Market Watch visibility |
|
||||
| `place_market_order`, `close_open_positions`, `update_sltp_for_open_positions`, `update_trailing_stop_loss_for_open_positions` | Order execution helpers (`dry_run` supported) |
|
||||
| `MarginVolume`, `OrderLimits`, `OrderExecutionResult` | Typed return contracts for order helpers |
|
||||
| `OrderSide`, `OrderFillingMode`, `OrderTimeMode`, `PositionSide`, `ExecutionStatus` | Typed enums for order helpers |
|
||||
| `ProjectionMode` | Literal type for `calculate_symbol_group_margin_ratio` projection |
|
||||
|
||||
`calculate_symbol_group_margin_ratio` accepts an optional `projection_mode`
|
||||
parameter (`"add"` by default). Pass `projection_mode="replace_symbol"` to
|
||||
subtract current exposure for `new_symbol` before adding the candidate margin —
|
||||
useful for reversal-style projections. mt5cli only calculates broker-facing
|
||||
exposure; downstream applications own thresholds, risk guard actions, and
|
||||
strategy policy.
|
||||
|
||||
`MT5Client.order_send()` and CLI `order-send --yes` are live execution paths.
|
||||
|
||||
@@ -125,13 +141,43 @@ and returned as `status="failed"` with normalized `request` / `response` details
|
||||
| `normalize_mt5_exception`, `call_with_normalized_errors`, `is_recoverable_mt5_error` | Error normalization and retry classification |
|
||||
| `Mt5Config`, `Mt5RuntimeError`, `Mt5TradingClient`, `Mt5TradingError` | Re-exported pdmt5 types for adapter convenience |
|
||||
|
||||
### Additional public exports (secondary)
|
||||
## Secondary public exports
|
||||
|
||||
The package root also exports schema, storage, and parsing helpers (for example
|
||||
`DataKind`, `Dataset`, `normalize_dataframe`, `export_dataframe`,
|
||||
`parse_timeframe`, `TIMEFRAME_MAP`). These are public but oriented toward export
|
||||
pipelines and advanced integration. Prefer the stable symbols above for core
|
||||
infrastructure.
|
||||
These names remain importable from `mt5cli` and are covered by
|
||||
`SECONDARY_PUBLIC_EXPORTS`, but they are oriented toward CLI/export/schema
|
||||
integrations, parsing, and lower-level MT5 access rather than the stable core
|
||||
SDK surface. Prefer the stable symbols above for downstream infrastructure
|
||||
adapters.
|
||||
|
||||
### Read-only MT5 data wrappers
|
||||
|
||||
Module-level helpers open a transient connection per call. Prefer `mt5_session`
|
||||
or `MT5Client` when making many requests in one process.
|
||||
|
||||
| Area | Symbols |
|
||||
| -------------------- | ---------------------------------------------------------------------------------------------------- |
|
||||
| Rates | `copy_rates_from`, `copy_rates_from_pos`, `copy_rates_range`, `latest_rates`, `collect_latest_rates` |
|
||||
| Ticks | `copy_ticks_from`, `copy_ticks_range`, `recent_ticks` |
|
||||
| Account / terminal | `account_info`, `terminal_info`, `mt5_version`, `last_error`, `mt5_summary`, `mt5_summary_as_df` |
|
||||
| Symbols / market | `symbols`, `symbol_info`, `symbol_info_tick`, `market_book`, `minimum_margins` |
|
||||
| Trading state (read) | `orders`, `positions`, `history_orders`, `history_deals`, `recent_history_deals` |
|
||||
| Multi-account rates | `collect_latest_rates_for_accounts` |
|
||||
|
||||
Use `mt5_version` for MetaTrader 5 terminal version data. The name `version` at
|
||||
the package root refers to `importlib.metadata.version` (package metadata), not
|
||||
the MT5 SDK helper.
|
||||
|
||||
### Schema, export, and parser helpers
|
||||
|
||||
| Area | Symbols |
|
||||
| -------------------- | ------------------------------------------------------------------------------------------------------------- |
|
||||
| Dataset contracts | `DataKind`, `Dataset`, `IfExists`, `DEDUP_KEYS`, `REQUIRED_COLUMNS`, `TIME_COLUMNS`, `KNOWN_MT5_TIME_COLUMNS` |
|
||||
| Schema normalization | `normalize_dataframe`, `normalize_time_columns`, `schema_columns`, `validate_schema` |
|
||||
| Export helpers | `detect_format`, `export_dataframe`, `export_dataframe_to_sqlite` |
|
||||
| Symbol parsing | `normalize_symbol`, `normalize_symbols` |
|
||||
| Time parsing | `ensure_utc`, `parse_date_range`, `parse_datetime`, `recent_window` |
|
||||
| MT5 parsing maps | `granularity_name`, `parse_tick_flags`, `parse_timeframe`, `TICK_FLAG_MAP`, `TIMEFRAME_MAP` |
|
||||
| Trading data shapes | `POSITION_COLUMNS` |
|
||||
|
||||
## CLI commands
|
||||
|
||||
@@ -144,7 +190,12 @@ The Typer application in `mt5cli.cli` exposes file-export commands documented in
|
||||
- Delegate to the same Python APIs described here; they are not duplicated
|
||||
business logic.
|
||||
|
||||
`order-send` requires `--yes` before placing live trades.
|
||||
`order-send` is the expert raw-request path; it requires `--yes` and a fully
|
||||
constructed request payload. `close-positions` is the safer high-level helper
|
||||
that closes open positions by `--symbol` or `--ticket` using
|
||||
`close_open_positions()`. Both `order-send --yes` and `close-positions --yes`
|
||||
are live execution paths. `close-positions --dry-run` previews close orders
|
||||
without placing them and does not require `--yes`.
|
||||
|
||||
## Internal helpers (not stable)
|
||||
|
||||
@@ -180,7 +231,7 @@ their own adapter layer.
|
||||
|
||||
## Contract verification
|
||||
|
||||
`tests/test_contracts.py` asserts that every name in `STABLE_SDK_EXPORTS` is
|
||||
importable from `mt5cli`, documents key closed-bar, rate-view, SQLite loading,
|
||||
account-resolution, and trading-session behaviors, and keeps the contract set
|
||||
aligned with `__all__`.
|
||||
`tests/test_contracts.py` asserts that every name in the stable and secondary
|
||||
tier sets is importable from `mt5cli`, documents key closed-bar, rate-view,
|
||||
SQLite loading, account-resolution, and trading-session behaviors, and keeps the
|
||||
tier sets aligned with `__all__`.
|
||||
|
||||
+25
-3
@@ -31,7 +31,7 @@ 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 `Mt5CliClient`; use
|
||||
row. `fetch_latest_closed_rates()` handles one connected `MT5Client`; 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
|
||||
@@ -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
|
||||
@@ -148,5 +170,5 @@ resulting `ValueError` is suppressed along with other recoverable errors.
|
||||
## Trading-capable sessions
|
||||
|
||||
For order placement and trading calculations, use the dedicated
|
||||
[Trading module](trading.md). The read-only `Mt5CliClient` and `mt5_session()`
|
||||
helpers in this module are unchanged.
|
||||
[Trading module](trading.md). Use `mt5_session()` / `MT5Client` for read-only
|
||||
collection.
|
||||
|
||||
+21
-12
@@ -31,7 +31,7 @@ finally:
|
||||
`login` accepts `int`, numeric `str`, or an empty string; empty strings are
|
||||
treated as unset. `path`, `password`, `server`, and `timeout` are forwarded to
|
||||
`pdmt5.Mt5Config`, and omitted `timeout` values keep the lower-level default.
|
||||
The read-only `Mt5CliClient` / `mt5_session()` API is unchanged.
|
||||
Use `mt5_session()` / `MT5Client` for read-only data collection.
|
||||
|
||||
## State and order helpers
|
||||
|
||||
@@ -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,17 +183,17 @@ 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
|
||||
Keep read-only data collection on `mt5_session()` / `MT5Client`; use
|
||||
`mt5_trading_session()` only where order placement or trading calculations are
|
||||
required.
|
||||
|
||||
+1
-1
@@ -29,7 +29,7 @@ pip install mt5cli
|
||||
|
||||
## Python API for downstream packages
|
||||
|
||||
Import `MT5Client` for generic MT5 data access, schema normalization, and optional order primitives. `Mt5CliClient` remains available as a backward-compatible alias.
|
||||
Import `MT5Client` for generic MT5 data access, schema normalization, and optional order primitives.
|
||||
|
||||
```python
|
||||
from datetime import UTC, datetime
|
||||
|
||||
+29
-3
@@ -11,7 +11,11 @@ from importlib.metadata import version
|
||||
from pdmt5 import Mt5Config, Mt5RuntimeError, Mt5TradingClient, Mt5TradingError
|
||||
|
||||
from .client import MT5Client, build_config, mt5_session
|
||||
from .contract import STABLE_SDK_EXPORTS
|
||||
from .contract import (
|
||||
PUBLIC_EXPORT_TIERS,
|
||||
SECONDARY_PUBLIC_EXPORTS,
|
||||
STABLE_SDK_EXPORTS,
|
||||
)
|
||||
from .converters import (
|
||||
ensure_utc,
|
||||
granularity_name,
|
||||
@@ -59,7 +63,6 @@ from .schemas import (
|
||||
)
|
||||
from .sdk import (
|
||||
AccountSpec,
|
||||
Mt5CliClient,
|
||||
ThrottledHistoryUpdater,
|
||||
account_info,
|
||||
collect_history,
|
||||
@@ -89,6 +92,7 @@ from .sdk import (
|
||||
resolve_account_spec,
|
||||
resolve_account_specs,
|
||||
substitute_env_placeholders,
|
||||
substitute_mapping_values,
|
||||
symbol_info,
|
||||
symbol_info_tick,
|
||||
symbols,
|
||||
@@ -116,10 +120,17 @@ from .trading import (
|
||||
OrderSide,
|
||||
OrderTimeMode,
|
||||
PositionSide,
|
||||
ProjectionMode,
|
||||
calculate_account_projected_margin_ratio,
|
||||
calculate_margin_and_volume,
|
||||
calculate_new_position_margin_ratio,
|
||||
calculate_positions_margin,
|
||||
calculate_positions_margin_by_symbol,
|
||||
calculate_positions_margin_safe,
|
||||
calculate_projected_margin_ratio,
|
||||
calculate_spread_ratio,
|
||||
calculate_symbol_group_margin_ratio,
|
||||
calculate_trailing_stop_updates,
|
||||
calculate_volume_by_margin,
|
||||
close_open_positions,
|
||||
create_trading_client,
|
||||
@@ -127,7 +138,9 @@ from .trading import (
|
||||
determine_order_limits,
|
||||
ensure_symbol_selected,
|
||||
estimate_order_margin,
|
||||
extract_tick_price,
|
||||
fetch_latest_closed_rates_for_trading_client,
|
||||
fetch_latest_closed_rates_indexed,
|
||||
get_account_snapshot,
|
||||
get_positions_frame,
|
||||
get_symbol_snapshot,
|
||||
@@ -136,6 +149,7 @@ from .trading import (
|
||||
normalize_order_volume,
|
||||
place_market_order,
|
||||
update_sltp_for_open_positions,
|
||||
update_trailing_stop_loss_for_open_positions,
|
||||
)
|
||||
from .utils import (
|
||||
TICK_FLAG_MAP,
|
||||
@@ -151,7 +165,9 @@ __all__ = [
|
||||
"DEDUP_KEYS",
|
||||
"KNOWN_MT5_TIME_COLUMNS",
|
||||
"POSITION_COLUMNS",
|
||||
"PUBLIC_EXPORT_TIERS",
|
||||
"REQUIRED_COLUMNS",
|
||||
"SECONDARY_PUBLIC_EXPORTS",
|
||||
"STABLE_SDK_EXPORTS",
|
||||
"TICK_FLAG_MAP",
|
||||
"TIMEFRAME_MAP",
|
||||
@@ -163,7 +179,6 @@ __all__ = [
|
||||
"IfExists",
|
||||
"MT5Client",
|
||||
"MarginVolume",
|
||||
"Mt5CliClient",
|
||||
"Mt5CliError",
|
||||
"Mt5Config",
|
||||
"Mt5ConnectionError",
|
||||
@@ -178,16 +193,23 @@ __all__ = [
|
||||
"OrderSide",
|
||||
"OrderTimeMode",
|
||||
"PositionSide",
|
||||
"ProjectionMode",
|
||||
"RateTarget",
|
||||
"ThrottledHistoryUpdater",
|
||||
"account_info",
|
||||
"build_config",
|
||||
"build_rate_targets",
|
||||
"build_rate_view_name",
|
||||
"calculate_account_projected_margin_ratio",
|
||||
"calculate_margin_and_volume",
|
||||
"calculate_new_position_margin_ratio",
|
||||
"calculate_positions_margin",
|
||||
"calculate_positions_margin_by_symbol",
|
||||
"calculate_positions_margin_safe",
|
||||
"calculate_projected_margin_ratio",
|
||||
"calculate_spread_ratio",
|
||||
"calculate_symbol_group_margin_ratio",
|
||||
"calculate_trailing_stop_updates",
|
||||
"calculate_volume_by_margin",
|
||||
"call_with_normalized_errors",
|
||||
"close_open_positions",
|
||||
@@ -212,8 +234,10 @@ __all__ = [
|
||||
"estimate_order_margin",
|
||||
"export_dataframe",
|
||||
"export_dataframe_to_sqlite",
|
||||
"extract_tick_price",
|
||||
"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",
|
||||
@@ -262,6 +286,7 @@ __all__ = [
|
||||
"resolve_rate_view_names",
|
||||
"schema_columns",
|
||||
"substitute_env_placeholders",
|
||||
"substitute_mapping_values",
|
||||
"symbol_info",
|
||||
"symbol_info_tick",
|
||||
"symbols",
|
||||
@@ -269,5 +294,6 @@ __all__ = [
|
||||
"update_history",
|
||||
"update_history_with_config",
|
||||
"update_sltp_for_open_positions",
|
||||
"update_trailing_stop_loss_for_open_positions",
|
||||
"validate_schema",
|
||||
]
|
||||
|
||||
+93
-2
@@ -2,17 +2,20 @@
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import logging
|
||||
from dataclasses import dataclass
|
||||
from datetime import datetime # noqa: TC003
|
||||
from pathlib import Path # noqa: TC003
|
||||
from typing import TYPE_CHECKING, Annotated, Any, cast
|
||||
|
||||
import pandas as pd
|
||||
import typer
|
||||
from pdmt5 import Mt5Config
|
||||
|
||||
from . import sdk
|
||||
from .client import MT5Client
|
||||
from .trading import OrderExecutionResult, close_open_positions, create_trading_client
|
||||
from .utils import (
|
||||
DATETIME_TYPE,
|
||||
REQUEST_TYPE,
|
||||
@@ -29,8 +32,6 @@ from .utils import (
|
||||
if TYPE_CHECKING:
|
||||
from collections.abc import Callable
|
||||
|
||||
import pandas as pd
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
@@ -600,6 +601,96 @@ def order_send(
|
||||
_export_command(ctx, lambda client: client.order_send(request))
|
||||
|
||||
|
||||
_EXECUTION_RESULT_COLUMNS: list[str] = [
|
||||
"status",
|
||||
"symbol",
|
||||
"order_side",
|
||||
"volume",
|
||||
"retcode",
|
||||
"comment",
|
||||
"request",
|
||||
"response",
|
||||
"dry_run",
|
||||
]
|
||||
|
||||
|
||||
def _execution_results_to_df(results: list[OrderExecutionResult]) -> pd.DataFrame:
|
||||
if not results:
|
||||
return pd.DataFrame(columns=_EXECUTION_RESULT_COLUMNS)
|
||||
rows = [
|
||||
{
|
||||
**r,
|
||||
"request": json.dumps(r["request"]),
|
||||
"response": json.dumps(r["response"]),
|
||||
}
|
||||
for r in results
|
||||
]
|
||||
return pd.DataFrame(rows)
|
||||
|
||||
|
||||
@app.command()
|
||||
def close_positions(
|
||||
ctx: typer.Context,
|
||||
symbol: Annotated[
|
||||
list[str] | None,
|
||||
typer.Option(
|
||||
"--symbol",
|
||||
"-s",
|
||||
help="Symbol to close (repeat for multiple symbols).",
|
||||
),
|
||||
] = None,
|
||||
ticket: Annotated[
|
||||
list[int] | None,
|
||||
typer.Option(
|
||||
"--ticket",
|
||||
"-t",
|
||||
help="Position ticket to close (repeat for multiple tickets).",
|
||||
),
|
||||
] = None,
|
||||
dry_run: Annotated[
|
||||
bool,
|
||||
typer.Option("--dry-run", help="Preview close orders without executing them."),
|
||||
] = False,
|
||||
yes: Annotated[
|
||||
bool,
|
||||
typer.Option("--yes", help="Confirm live position closing."),
|
||||
] = False,
|
||||
) -> None:
|
||||
"""Close open positions by symbol or ticket.
|
||||
|
||||
Delegates to :func:`mt5cli.trading.close_open_positions`. At least one
|
||||
``--symbol`` or ``--ticket`` must be provided to avoid accidentally closing
|
||||
all positions. Use ``--dry-run`` to preview without executing; ``--yes`` is
|
||||
required for live execution.
|
||||
|
||||
``order-send`` is the expert raw-request path. ``close-positions`` is the
|
||||
safer high-level helper that builds correct close requests automatically.
|
||||
|
||||
Raises:
|
||||
typer.BadParameter: If neither ``--symbol`` nor ``--ticket`` is given,
|
||||
or if ``--yes`` is missing for a live (non-dry-run) run.
|
||||
"""
|
||||
if not symbol and not ticket:
|
||||
msg = "Provide at least one --symbol or --ticket to close positions."
|
||||
raise typer.BadParameter(msg)
|
||||
if not dry_run and not yes:
|
||||
msg = "Pass --yes to close live positions."
|
||||
raise typer.BadParameter(msg, param_hint="--yes")
|
||||
export_ctx = _get_export_context(ctx)
|
||||
client = create_trading_client(config=export_ctx.config)
|
||||
try:
|
||||
results = close_open_positions(
|
||||
client,
|
||||
symbols=list(symbol) if symbol else None,
|
||||
tickets=list(ticket) if ticket else None,
|
||||
dry_run=dry_run,
|
||||
)
|
||||
finally:
|
||||
client.shutdown()
|
||||
df = _execution_results_to_df(results)
|
||||
_execute_export(ctx, lambda: df)
|
||||
|
||||
|
||||
@app.command()
|
||||
def collect_history(
|
||||
ctx: typer.Context,
|
||||
|
||||
+1
-3
@@ -24,9 +24,7 @@ class MT5Client(Mt5CliClient):
|
||||
"""Public client for generic MT5 data access and order primitives.
|
||||
|
||||
Extends the read-only SDK client with optional order check/send helpers and
|
||||
exposes the same connection lifecycle as :class:`~mt5cli.sdk.Mt5CliClient`.
|
||||
Downstream applications such as private trading packages should prefer this
|
||||
type over the legacy ``Mt5CliClient`` name.
|
||||
exposes the same connection lifecycle as :func:`mt5_session`.
|
||||
|
||||
mt5cli intentionally exposes minimal execution primitives only. Trading
|
||||
decisions, signals, strategies, backtests, and optimization remain the
|
||||
|
||||
+75
-29
@@ -1,11 +1,10 @@
|
||||
"""Stable downstream SDK export names for mt5cli."""
|
||||
"""Downstream SDK export tiers for mt5cli."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
STABLE_SDK_EXPORTS: frozenset[str] = frozenset({
|
||||
"AccountSpec",
|
||||
"MT5Client",
|
||||
"Mt5CliClient",
|
||||
"Mt5CliError",
|
||||
"Mt5Config",
|
||||
"Mt5ConnectionError",
|
||||
@@ -18,71 +17,57 @@ STABLE_SDK_EXPORTS: frozenset[str] = frozenset({
|
||||
"OrderSide",
|
||||
"OrderTimeMode",
|
||||
"PositionSide",
|
||||
"ProjectionMode",
|
||||
"ExecutionStatus",
|
||||
"MarginVolume",
|
||||
"OrderExecutionResult",
|
||||
"OrderLimits",
|
||||
"RateTarget",
|
||||
"ThrottledHistoryUpdater",
|
||||
"account_info",
|
||||
"build_config",
|
||||
"build_rate_targets",
|
||||
"build_rate_view_name",
|
||||
"calculate_account_projected_margin_ratio",
|
||||
"calculate_margin_and_volume",
|
||||
"calculate_new_position_margin_ratio",
|
||||
"calculate_projected_margin_ratio",
|
||||
"calculate_positions_margin",
|
||||
"calculate_positions_margin_by_symbol",
|
||||
"calculate_positions_margin_safe",
|
||||
"calculate_spread_ratio",
|
||||
"calculate_symbol_group_margin_ratio",
|
||||
"calculate_trailing_stop_updates",
|
||||
"calculate_volume_by_margin",
|
||||
"call_with_normalized_errors",
|
||||
"close_open_positions",
|
||||
"collect_history",
|
||||
"collect_latest_closed_rates_by_granularity",
|
||||
"collect_latest_closed_rates_for_accounts",
|
||||
"collect_latest_rates",
|
||||
"collect_latest_rates_for_accounts",
|
||||
"collect_latest_rates_for_accounts_with_retries",
|
||||
"copy_rates_from",
|
||||
"copy_rates_from_pos",
|
||||
"copy_rates_range",
|
||||
"copy_ticks_from",
|
||||
"copy_ticks_range",
|
||||
"create_trading_client",
|
||||
"detect_position_side",
|
||||
"determine_order_limits",
|
||||
"drop_forming_rate_bar",
|
||||
"ensure_symbol_selected",
|
||||
"estimate_order_margin",
|
||||
"export_dataframe",
|
||||
"export_dataframe_to_sqlite",
|
||||
"extract_tick_price",
|
||||
"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",
|
||||
"get_tick_snapshot",
|
||||
"history_deals",
|
||||
"history_orders",
|
||||
"is_recoverable_mt5_error",
|
||||
"last_error",
|
||||
"latest_rates",
|
||||
"load_rate_data",
|
||||
"load_rate_data_from_connection",
|
||||
"load_rate_series_by_granularity",
|
||||
"load_rate_series_from_sqlite",
|
||||
"market_book",
|
||||
"minimum_margins",
|
||||
"mt5_session",
|
||||
"mt5_summary",
|
||||
"mt5_summary_as_df",
|
||||
"mt5_trading_session",
|
||||
"mt5_version",
|
||||
"normalize_mt5_exception",
|
||||
"normalize_order_volume",
|
||||
"orders",
|
||||
"place_market_order",
|
||||
"positions",
|
||||
"recent_history_deals",
|
||||
"recent_ticks",
|
||||
"resolve_account_spec",
|
||||
"resolve_account_specs",
|
||||
"resolve_history_datasets",
|
||||
@@ -93,13 +78,74 @@ STABLE_SDK_EXPORTS: frozenset[str] = frozenset({
|
||||
"resolve_rate_view_name",
|
||||
"resolve_rate_view_names",
|
||||
"substitute_env_placeholders",
|
||||
"substitute_mapping_values",
|
||||
"update_history",
|
||||
"update_history_with_config",
|
||||
"update_sltp_for_open_positions",
|
||||
"update_trailing_stop_loss_for_open_positions",
|
||||
})
|
||||
|
||||
SECONDARY_PUBLIC_EXPORTS: frozenset[str] = frozenset({
|
||||
"DEDUP_KEYS",
|
||||
"DataKind",
|
||||
"Dataset",
|
||||
"IfExists",
|
||||
"KNOWN_MT5_TIME_COLUMNS",
|
||||
"POSITION_COLUMNS",
|
||||
"REQUIRED_COLUMNS",
|
||||
"TICK_FLAG_MAP",
|
||||
"TIMEFRAME_MAP",
|
||||
"TIME_COLUMNS",
|
||||
"account_info",
|
||||
"collect_latest_rates",
|
||||
"collect_latest_rates_for_accounts",
|
||||
"copy_rates_from",
|
||||
"copy_rates_from_pos",
|
||||
"copy_rates_range",
|
||||
"copy_ticks_from",
|
||||
"copy_ticks_range",
|
||||
"detect_format",
|
||||
"ensure_utc",
|
||||
"export_dataframe",
|
||||
"export_dataframe_to_sqlite",
|
||||
"granularity_name",
|
||||
"history_deals",
|
||||
"history_orders",
|
||||
"last_error",
|
||||
"latest_rates",
|
||||
"market_book",
|
||||
"minimum_margins",
|
||||
"mt5_summary",
|
||||
"mt5_summary_as_df",
|
||||
"mt5_version",
|
||||
"normalize_dataframe",
|
||||
"normalize_symbol",
|
||||
"normalize_symbols",
|
||||
"normalize_time_columns",
|
||||
"orders",
|
||||
"parse_date_range",
|
||||
"parse_datetime",
|
||||
"parse_tick_flags",
|
||||
"parse_timeframe",
|
||||
"positions",
|
||||
"recent_history_deals",
|
||||
"recent_ticks",
|
||||
"recent_window",
|
||||
"schema_columns",
|
||||
"symbol_info",
|
||||
"symbol_info_tick",
|
||||
"symbols",
|
||||
"terminal_info",
|
||||
"update_history",
|
||||
"update_history_with_config",
|
||||
"update_sltp_for_open_positions",
|
||||
"validate_schema",
|
||||
})
|
||||
|
||||
__all__ = ["STABLE_SDK_EXPORTS"]
|
||||
PUBLIC_EXPORT_TIERS: dict[str, frozenset[str]] = {
|
||||
"stable": STABLE_SDK_EXPORTS,
|
||||
"secondary": SECONDARY_PUBLIC_EXPORTS,
|
||||
}
|
||||
|
||||
__all__ = [
|
||||
"PUBLIC_EXPORT_TIERS",
|
||||
"SECONDARY_PUBLIC_EXPORTS",
|
||||
"STABLE_SDK_EXPORTS",
|
||||
]
|
||||
|
||||
+157
-12
@@ -40,7 +40,7 @@ from .utils import (
|
||||
from .utils import coerce_login as _coerce_login
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from collections.abc import Callable, Iterator, Sequence
|
||||
from collections.abc import Callable, Collection, Iterator, Sequence
|
||||
|
||||
UpdateHistoryBackend = Callable[..., None]
|
||||
|
||||
@@ -142,6 +142,7 @@ __all__ = [
|
||||
"resolve_account_spec",
|
||||
"resolve_account_specs",
|
||||
"substitute_env_placeholders",
|
||||
"substitute_mapping_values",
|
||||
"symbol_info",
|
||||
"symbol_info_tick",
|
||||
"symbols",
|
||||
@@ -305,19 +306,47 @@ def _fetch_minimum_margins(client: Mt5DataClient, symbol: str) -> pd.DataFrame:
|
||||
def build_config(
|
||||
*,
|
||||
path: str | None = None,
|
||||
login: int | None = None,
|
||||
login: int | str | None = None,
|
||||
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. Integers are preserved. String
|
||||
values are coerced: empty or whitespace-only strings become
|
||||
``None``; numeric strings such as ``"12345"`` are converted to
|
||||
``int``; non-numeric strings raise ``ValueError``. When
|
||||
``allow_whole_dollar_env=True``, ``$ENV_NAME`` and
|
||||
``${ENV_NAME}`` placeholders are expanded before coercion.
|
||||
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``, ``login``, ``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 isinstance(login, str):
|
||||
login = substitute_env_placeholders(login, 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,
|
||||
login=_coerce_login(login),
|
||||
password=password,
|
||||
server=server,
|
||||
timeout=timeout,
|
||||
@@ -1376,13 +1405,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 +1428,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 +1450,81 @@ def substitute_env_placeholders(value: str) -> str:
|
||||
return "".join(parts)
|
||||
|
||||
|
||||
def _resolve_field(override: str | None, account_value: str | None) -> str | None:
|
||||
def substitute_mapping_values(
|
||||
data: object,
|
||||
*,
|
||||
keys: Collection[str],
|
||||
allow_whole_dollar_env: bool = False,
|
||||
blank_string_keys_as_none: Collection[str] = (),
|
||||
) -> object:
|
||||
"""Recursively substitute environment placeholders for selected mapping keys.
|
||||
|
||||
Traverses nested dicts and lists, expanding ``${ENV_VAR}`` (and
|
||||
``$ENV_NAME`` when ``allow_whole_dollar_env=True``) in string values
|
||||
whose immediate parent dict key is in ``keys``. Fields whose key is
|
||||
not in ``keys`` are preserved exactly, including literal dollar signs.
|
||||
Strings that are direct elements of a list are never substituted;
|
||||
substitution only applies to strings that are immediate dict values.
|
||||
|
||||
This is a generic downstream config utility. Key names such as
|
||||
``mt5_login`` or ``mt5_password`` must be supplied by the caller;
|
||||
mt5cli does not hard-code any application-specific key names.
|
||||
Callers are responsible for ensuring ``data`` has bounded nesting depth;
|
||||
deeply nested or self-referential structures will hit Python's recursion
|
||||
limit.
|
||||
|
||||
Args:
|
||||
data: Arbitrarily nested dict/list/scalar value to process.
|
||||
keys: Mapping keys whose string values receive placeholder
|
||||
substitution.
|
||||
allow_whole_dollar_env: When ``True``, a string that is exactly
|
||||
``$ENV_NAME`` (whole value) is also expanded from the
|
||||
environment in addition to ``${ENV_NAME}`` placeholders.
|
||||
Default ``False`` expands ``${ENV_NAME}`` only.
|
||||
blank_string_keys_as_none: Mapping keys for which blank strings
|
||||
(after any substitution) are normalised to ``None``. A key
|
||||
may appear in ``blank_string_keys_as_none`` without also
|
||||
appearing in ``keys``.
|
||||
|
||||
Returns:
|
||||
The processed value. Dicts and lists are rebuilt into new
|
||||
containers with selected string values substituted and
|
||||
blank-normalised. Scalar inputs (non-dict, non-list) are
|
||||
returned as-is.
|
||||
"""
|
||||
keys_set: frozenset[str] = frozenset(keys)
|
||||
blank_keys_set: frozenset[str] = frozenset(blank_string_keys_as_none)
|
||||
|
||||
def _visit(node: object, current_key: str | None) -> object:
|
||||
if isinstance(node, dict):
|
||||
typed = cast("dict[object, object]", node)
|
||||
return {
|
||||
k: _visit(v, k if isinstance(k, str) else None)
|
||||
for k, v in typed.items()
|
||||
}
|
||||
if isinstance(node, list):
|
||||
typed_list = cast("list[object]", node)
|
||||
return [_visit(item, None) for item in typed_list]
|
||||
if not isinstance(node, str):
|
||||
return node
|
||||
text = node
|
||||
if current_key in keys_set:
|
||||
text = substitute_env_placeholders(
|
||||
node, allow_whole_dollar_env=allow_whole_dollar_env
|
||||
)
|
||||
if current_key in blank_keys_set and not text.strip():
|
||||
return None
|
||||
return text
|
||||
|
||||
return _visit(data, 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 +1534,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 +1555,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 +1573,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 +1589,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 +1601,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 +1625,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 +1639,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 +1656,7 @@ def resolve_account_specs(
|
||||
server=server,
|
||||
path=path,
|
||||
timeout=timeout,
|
||||
allow_whole_dollar_env=allow_whole_dollar_env,
|
||||
)
|
||||
for account in accounts
|
||||
]
|
||||
|
||||
+542
-71
@@ -2,27 +2,30 @@
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
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
|
||||
from pdmt5 import Mt5Config, Mt5TradingClient, Mt5TradingError
|
||||
from pdmt5 import Mt5Config, Mt5RuntimeError, Mt5TradingClient, Mt5TradingError
|
||||
|
||||
from .history import drop_forming_rate_bar
|
||||
from .sdk import build_config
|
||||
from .utils import coerce_login as _coerce_login
|
||||
from .utils import parse_timeframe
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from collections.abc import Iterator, Sequence
|
||||
from collections.abc import Iterator, Mapping, Sequence
|
||||
|
||||
_logger = logging.getLogger(__name__)
|
||||
|
||||
PositionSide = Literal["long", "short"]
|
||||
OrderSide = Literal["BUY", "SELL"]
|
||||
OrderFillingMode = Literal["IOC", "FOK", "RETURN"]
|
||||
OrderTimeMode = Literal["GTC", "DAY", "SPECIFIED", "SPECIFIED_DAY"]
|
||||
ExecutionStatus = Literal["executed", "dry_run", "skipped", "failed"]
|
||||
ProjectionMode = Literal["add", "replace_symbol"]
|
||||
|
||||
|
||||
class MarginVolume(TypedDict):
|
||||
@@ -125,10 +128,17 @@ __all__ = [
|
||||
"OrderSide",
|
||||
"OrderTimeMode",
|
||||
"PositionSide",
|
||||
"ProjectionMode",
|
||||
"calculate_account_projected_margin_ratio",
|
||||
"calculate_margin_and_volume",
|
||||
"calculate_new_position_margin_ratio",
|
||||
"calculate_positions_margin",
|
||||
"calculate_positions_margin_by_symbol",
|
||||
"calculate_positions_margin_safe",
|
||||
"calculate_projected_margin_ratio",
|
||||
"calculate_spread_ratio",
|
||||
"calculate_symbol_group_margin_ratio",
|
||||
"calculate_trailing_stop_updates",
|
||||
"calculate_volume_by_margin",
|
||||
"close_open_positions",
|
||||
"create_trading_client",
|
||||
@@ -136,7 +146,9 @@ __all__ = [
|
||||
"determine_order_limits",
|
||||
"ensure_symbol_selected",
|
||||
"estimate_order_margin",
|
||||
"extract_tick_price",
|
||||
"fetch_latest_closed_rates_for_trading_client",
|
||||
"fetch_latest_closed_rates_indexed",
|
||||
"get_account_snapshot",
|
||||
"get_positions_frame",
|
||||
"get_symbol_snapshot",
|
||||
@@ -145,6 +157,7 @@ __all__ = [
|
||||
"normalize_order_volume",
|
||||
"place_market_order",
|
||||
"update_sltp_for_open_positions",
|
||||
"update_trailing_stop_loss_for_open_positions",
|
||||
]
|
||||
|
||||
|
||||
@@ -422,6 +435,30 @@ def _optional_price(value: object) -> float | None:
|
||||
return price
|
||||
|
||||
|
||||
def extract_tick_price(tick: Mapping[str, object], key: str) -> float | None:
|
||||
"""Return a positive finite float from tick[key], or None if invalid.
|
||||
|
||||
Accepts int, float, or numeric string values. Returns None when the key is
|
||||
missing, the value is None, non-numeric, NaN, infinite, zero, or negative.
|
||||
Booleans are treated as non-numeric and return None.
|
||||
"""
|
||||
value = tick.get(key)
|
||||
if value is None or isinstance(value, bool):
|
||||
return None
|
||||
if isinstance(value, int | float):
|
||||
price = float(value)
|
||||
elif isinstance(value, str):
|
||||
try:
|
||||
price = float(value)
|
||||
except ValueError:
|
||||
return None
|
||||
else:
|
||||
return None
|
||||
if not isfinite(price) or price <= 0:
|
||||
return None
|
||||
return price
|
||||
|
||||
|
||||
def _success_retcodes(mt5: object) -> frozenset[int]:
|
||||
values = {
|
||||
value
|
||||
@@ -460,9 +497,10 @@ def _calculate_min_volume_if_affordable(
|
||||
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"]
|
||||
if not isinstance(price, int | float) or price <= 0:
|
||||
price = extract_tick_price(
|
||||
get_tick_snapshot(client, symbol), "ask" if side == "BUY" else "bid"
|
||||
)
|
||||
if price is None:
|
||||
msg = f"Tick price is unavailable for {symbol!r}."
|
||||
raise Mt5TradingError(msg)
|
||||
order_type = (
|
||||
@@ -620,14 +658,14 @@ def estimate_order_margin(
|
||||
raise Mt5TradingError(msg)
|
||||
side = _normalize_order_side(order_side)
|
||||
tick = get_tick_snapshot(client, symbol)
|
||||
price = tick["ask"] if side == "BUY" else tick["bid"]
|
||||
if not isinstance(price, int | float) or price <= 0 or not isfinite(price):
|
||||
price = extract_tick_price(tick, "ask" if side == "BUY" else "bid")
|
||||
if price is None:
|
||||
msg = f"Tick price is unavailable for {symbol!r}."
|
||||
raise Mt5TradingError(msg)
|
||||
order_type = (
|
||||
client.mt5.ORDER_TYPE_BUY if side == "BUY" else client.mt5.ORDER_TYPE_SELL
|
||||
)
|
||||
raw_margin = client.order_calc_margin(order_type, symbol, volume, float(price))
|
||||
raw_margin = client.order_calc_margin(order_type, symbol, volume, price)
|
||||
try:
|
||||
margin = float(raw_margin)
|
||||
except (TypeError, ValueError) as exc:
|
||||
@@ -681,22 +719,85 @@ def calculate_positions_margin(
|
||||
return total
|
||||
|
||||
|
||||
def calculate_positions_margin_by_symbol(
|
||||
client: Mt5TradingClient,
|
||||
*,
|
||||
symbols: Sequence[str],
|
||||
suppress_errors: bool = True,
|
||||
) -> dict[str, float]:
|
||||
"""Return per-symbol estimated margin for open positions.
|
||||
|
||||
Computes margin for each unique input symbol independently using the strict
|
||||
:func:`calculate_positions_margin` helper. Duplicates are deduplicated in
|
||||
first-seen order.
|
||||
|
||||
Args:
|
||||
client: Connected ``Mt5TradingClient`` instance.
|
||||
symbols: Symbols to compute margin for.
|
||||
suppress_errors: When ``True``, log and skip symbols that raise
|
||||
``Mt5TradingError``, ``Mt5RuntimeError``, or ``AttributeError``.
|
||||
When ``False``, re-raise the first failure.
|
||||
|
||||
Returns:
|
||||
Mapping of symbol to margin total in first-seen unique-symbol order.
|
||||
Returns an empty dict when ``symbols`` is empty or all symbols fail
|
||||
with ``suppress_errors=True``.
|
||||
|
||||
Raises:
|
||||
Mt5TradingError: When a symbol raises ``Mt5TradingError`` and
|
||||
``suppress_errors=False``.
|
||||
Mt5RuntimeError: When a symbol raises ``Mt5RuntimeError`` and
|
||||
``suppress_errors=False``.
|
||||
AttributeError: When a symbol raises ``AttributeError`` and
|
||||
``suppress_errors=False``.
|
||||
"""
|
||||
result: dict[str, float] = {}
|
||||
for symbol in dict.fromkeys(symbols):
|
||||
try:
|
||||
result[symbol] = calculate_positions_margin(client, symbols=[symbol])
|
||||
except (Mt5TradingError, Mt5RuntimeError, AttributeError) as exc:
|
||||
if not suppress_errors:
|
||||
raise
|
||||
_logger.warning("Skipping margin for %r: %s", symbol, exc)
|
||||
return result
|
||||
|
||||
|
||||
def calculate_positions_margin_safe(
|
||||
client: Mt5TradingClient,
|
||||
*,
|
||||
symbols: Sequence[str],
|
||||
) -> float:
|
||||
"""Return the total estimated margin for open positions across symbols.
|
||||
|
||||
Internally calls :func:`calculate_positions_margin_by_symbol` with
|
||||
``suppress_errors=True``. Failed symbols are silently skipped.
|
||||
|
||||
Args:
|
||||
client: Connected ``Mt5TradingClient`` instance.
|
||||
symbols: Symbols to include.
|
||||
|
||||
Returns:
|
||||
Sum of per-symbol margins; ``0.0`` when no symbols or all fail.
|
||||
"""
|
||||
return sum(
|
||||
calculate_positions_margin_by_symbol(client, symbols=symbols).values(),
|
||||
0.0,
|
||||
)
|
||||
|
||||
|
||||
def calculate_spread_ratio(client: Mt5TradingClient, symbol: str) -> float:
|
||||
"""Return ``(ask - bid) / ((ask + bid) / 2)`` for the latest tick.
|
||||
|
||||
Raises:
|
||||
Mt5TradingError: If bid or ask is unavailable or non-positive.
|
||||
Mt5TradingError: If bid or ask is unavailable.
|
||||
"""
|
||||
tick = get_tick_snapshot(client, symbol)
|
||||
bid = tick.get("bid")
|
||||
ask = tick.get("ask")
|
||||
if not isinstance(bid, int | float) or not isinstance(ask, int | float):
|
||||
bid = extract_tick_price(tick, "bid")
|
||||
ask = extract_tick_price(tick, "ask")
|
||||
if bid is None or ask is None:
|
||||
msg = f"Tick bid/ask is unavailable for {symbol!r}."
|
||||
raise Mt5TradingError(msg)
|
||||
if bid <= 0 or ask <= 0:
|
||||
msg = f"Tick bid/ask must be positive for {symbol!r}."
|
||||
raise Mt5TradingError(msg)
|
||||
return (float(ask) - float(bid)) / ((float(ask) + float(bid)) / 2.0)
|
||||
return (ask - bid) / ((ask + bid) / 2.0)
|
||||
|
||||
|
||||
def calculate_new_position_margin_ratio(
|
||||
@@ -719,9 +820,10 @@ def calculate_new_position_margin_ratio(
|
||||
margin = float(account.get("margin") or 0.0)
|
||||
if new_position_side is not None and new_position_volume > 0:
|
||||
side = _normalize_order_side(new_position_side)
|
||||
tick = get_tick_snapshot(client, symbol)
|
||||
price = tick["ask"] if side == "BUY" else tick["bid"]
|
||||
if not isinstance(price, int | float) or price <= 0:
|
||||
price = extract_tick_price(
|
||||
get_tick_snapshot(client, symbol), "ask" if side == "BUY" else "bid"
|
||||
)
|
||||
if price is None:
|
||||
msg = f"Tick price is unavailable for {symbol!r}."
|
||||
raise Mt5TradingError(msg)
|
||||
order_type = (
|
||||
@@ -733,6 +835,169 @@ def calculate_new_position_margin_ratio(
|
||||
return margin / equity
|
||||
|
||||
|
||||
def _account_equity(client: Mt5TradingClient) -> float:
|
||||
account = get_account_snapshot(client)
|
||||
return _required_account_number(account, "equity", allow_zero=False)
|
||||
|
||||
|
||||
def _required_account_number(
|
||||
account: Mapping[str, object],
|
||||
field: str,
|
||||
*,
|
||||
allow_zero: bool,
|
||||
) -> float:
|
||||
raw_value = account.get(field)
|
||||
if isinstance(raw_value, bool) or not isinstance(raw_value, Real):
|
||||
msg = f"Account {field} must be a finite number to calculate margin ratio."
|
||||
raise Mt5TradingError(msg)
|
||||
value = float(raw_value)
|
||||
if (
|
||||
not isfinite(value)
|
||||
or (not allow_zero and value <= 0)
|
||||
or (allow_zero and value < 0)
|
||||
):
|
||||
msg = (
|
||||
f"Account {field} must be a non-negative finite number."
|
||||
if allow_zero
|
||||
else f"Account {field} must be a positive finite number."
|
||||
)
|
||||
raise Mt5TradingError(msg)
|
||||
return value
|
||||
|
||||
|
||||
def calculate_account_projected_margin_ratio(
|
||||
client: Mt5TradingClient,
|
||||
*,
|
||||
symbol: str | None = None,
|
||||
new_position_side: OrderSide | None = None,
|
||||
new_position_volume: float = 0.0,
|
||||
) -> float:
|
||||
"""Return account-wide current plus optional new-position margin over equity.
|
||||
|
||||
Current exposure comes from the broker account snapshot ``margin`` field so
|
||||
unrelated open positions remain in the baseline. Optional projected
|
||||
exposure is added via :func:`estimate_order_margin` only when a symbol, side,
|
||||
and positive volume are all supplied.
|
||||
|
||||
"""
|
||||
account = get_account_snapshot(client)
|
||||
equity = _required_account_number(account, "equity", allow_zero=False)
|
||||
margin = _required_account_number(account, "margin", allow_zero=True)
|
||||
if symbol is not None and new_position_side is not None and new_position_volume > 0:
|
||||
margin += estimate_order_margin(
|
||||
client,
|
||||
symbol,
|
||||
new_position_side,
|
||||
new_position_volume,
|
||||
)
|
||||
return margin / equity
|
||||
|
||||
|
||||
def calculate_projected_margin_ratio(
|
||||
client: Mt5TradingClient,
|
||||
*,
|
||||
symbol: str,
|
||||
new_position_side: OrderSide | None = None,
|
||||
new_position_volume: float = 0.0,
|
||||
) -> float:
|
||||
"""Return estimated current plus optional new-position margin over equity.
|
||||
|
||||
Current exposure is estimated from open positions with
|
||||
:func:`calculate_positions_margin`. Optional projected exposure is added via
|
||||
:func:`estimate_order_margin`. Thresholds and guard actions are intentionally
|
||||
left to downstream applications.
|
||||
|
||||
Account equity, position margin, and optional projected margin errors from
|
||||
the composed MT5 helpers propagate to the caller.
|
||||
"""
|
||||
equity = _account_equity(client)
|
||||
margin = calculate_positions_margin(client, symbols=[symbol])
|
||||
if new_position_side is not None and new_position_volume > 0:
|
||||
margin += estimate_order_margin(
|
||||
client,
|
||||
symbol,
|
||||
new_position_side,
|
||||
new_position_volume,
|
||||
)
|
||||
return margin / equity
|
||||
|
||||
|
||||
def _validate_projection_mode(projection_mode: str) -> ProjectionMode:
|
||||
if projection_mode not in {"add", "replace_symbol"}:
|
||||
msg = (
|
||||
f"Unsupported projection mode: {projection_mode!r}. "
|
||||
"Expected 'add' or 'replace_symbol'."
|
||||
)
|
||||
raise ValueError(msg)
|
||||
return cast("ProjectionMode", projection_mode)
|
||||
|
||||
|
||||
def calculate_symbol_group_margin_ratio(
|
||||
client: Mt5TradingClient,
|
||||
*,
|
||||
symbols: Sequence[str],
|
||||
new_symbol: str | None = None,
|
||||
new_position_side: OrderSide | None = None,
|
||||
new_position_volume: float = 0.0,
|
||||
suppress_errors: bool = True,
|
||||
projection_mode: ProjectionMode = "add",
|
||||
) -> float:
|
||||
"""Return estimated symbol-group margin over account equity.
|
||||
|
||||
Per-symbol current exposure is summed with
|
||||
:func:`calculate_positions_margin_by_symbol`. When ``new_symbol`` is inside
|
||||
the input symbol group and candidate side/volume are provided, projected order
|
||||
margin is applied according to ``projection_mode``:
|
||||
|
||||
- ``"add"`` (default): adds candidate margin to the group total.
|
||||
- ``"replace_symbol"``: subtracts current margin for ``new_symbol``, then
|
||||
adds candidate margin. Useful for reversal-style projections where the new
|
||||
order is intended to replace existing exposure for that symbol.
|
||||
|
||||
If the candidate margin estimation fails, the subtraction is also skipped so
|
||||
the operation is atomic. Invalid equity always raises to fail closed.
|
||||
|
||||
Raises:
|
||||
AttributeError: When symbol margin lookup or projected margin lookup
|
||||
fails and ``suppress_errors`` is ``False``.
|
||||
Mt5RuntimeError: When symbol margin lookup or projected margin lookup
|
||||
fails and ``suppress_errors`` is ``False``.
|
||||
Mt5TradingError: When account equity is invalid, or when symbol margin
|
||||
lookup or projected margin lookup fails and ``suppress_errors`` is
|
||||
``False``.
|
||||
"""
|
||||
projection_mode = _validate_projection_mode(projection_mode)
|
||||
equity = _account_equity(client)
|
||||
unique_symbols = list(dict.fromkeys(symbols))
|
||||
per_symbol = calculate_positions_margin_by_symbol(
|
||||
client,
|
||||
symbols=unique_symbols,
|
||||
suppress_errors=suppress_errors,
|
||||
)
|
||||
margin = sum(per_symbol.values(), 0.0)
|
||||
if (
|
||||
new_symbol in unique_symbols
|
||||
and new_position_side is not None
|
||||
and new_position_volume > 0
|
||||
):
|
||||
try:
|
||||
candidate_margin = estimate_order_margin(
|
||||
client,
|
||||
new_symbol,
|
||||
new_position_side,
|
||||
new_position_volume,
|
||||
)
|
||||
except (Mt5TradingError, Mt5RuntimeError, AttributeError):
|
||||
if not suppress_errors:
|
||||
raise
|
||||
_logger.warning("Skipping projected margin for %r.", new_symbol)
|
||||
else:
|
||||
if projection_mode == "replace_symbol":
|
||||
margin = max(0.0, margin - per_symbol.get(new_symbol, 0.0))
|
||||
margin += candidate_margin
|
||||
return margin / equity
|
||||
|
||||
|
||||
def calculate_margin_and_volume(
|
||||
client: Mt5TradingClient,
|
||||
symbol: str,
|
||||
@@ -779,28 +1044,8 @@ def calculate_margin_and_volume(
|
||||
"SELL",
|
||||
)
|
||||
else:
|
||||
native_calculate_volume = getattr(client, "calculate_volume_by_margin", None)
|
||||
if callable(native_calculate_volume):
|
||||
buy_volume = float(
|
||||
cast(
|
||||
"float | int | str",
|
||||
native_calculate_volume(symbol, trade_margin, "BUY"),
|
||||
),
|
||||
)
|
||||
sell_volume = float(
|
||||
cast(
|
||||
"float | int | str",
|
||||
native_calculate_volume(symbol, trade_margin, "SELL"),
|
||||
),
|
||||
)
|
||||
else:
|
||||
buy_volume = calculate_volume_by_margin(client, symbol, trade_margin, "BUY")
|
||||
sell_volume = calculate_volume_by_margin(
|
||||
client,
|
||||
symbol,
|
||||
trade_margin,
|
||||
"SELL",
|
||||
)
|
||||
buy_volume = calculate_volume_by_margin(client, symbol, trade_margin, "BUY")
|
||||
sell_volume = calculate_volume_by_margin(client, symbol, trade_margin, "SELL")
|
||||
try:
|
||||
symbol_info = get_symbol_snapshot(client, symbol)
|
||||
volume_min = float(symbol_info.get("volume_min") or 0.0)
|
||||
@@ -829,7 +1074,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,9 +1091,10 @@ 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"]
|
||||
if not isinstance(price, int | float) or price <= 0:
|
||||
price = extract_tick_price(
|
||||
get_tick_snapshot(client, symbol), "ask" if side == "BUY" else "bid"
|
||||
)
|
||||
if price is None:
|
||||
msg = f"Tick price is unavailable for {symbol!r}."
|
||||
raise Mt5TradingError(msg)
|
||||
order_type = (
|
||||
@@ -855,11 +1103,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(
|
||||
@@ -895,11 +1170,11 @@ def determine_order_limits(
|
||||
_require_protective_ratio(take_profit_ratio, "take_profit_limit_ratio")
|
||||
normalized_side = _position_side_from_order_side(side)
|
||||
tick = get_tick_snapshot(client, symbol)
|
||||
entry_value = tick["ask"] if normalized_side == "long" else tick["bid"]
|
||||
if not isinstance(entry_value, int | float):
|
||||
entry_key = "ask" if normalized_side == "long" else "bid"
|
||||
entry = extract_tick_price(tick, entry_key)
|
||||
if entry is None:
|
||||
msg = f"Tick price is unavailable for {symbol!r}."
|
||||
raise Mt5TradingError(msg)
|
||||
entry = float(entry_value)
|
||||
try:
|
||||
symbol_info = get_symbol_snapshot(client, symbol)
|
||||
except (AttributeError, KeyError, TypeError, ValueError):
|
||||
@@ -975,8 +1250,8 @@ def place_market_order(
|
||||
if not dry_run:
|
||||
ensure_symbol_selected(client, symbol)
|
||||
tick = get_tick_snapshot(client, symbol)
|
||||
price = tick["ask"] if side == "BUY" else tick["bid"]
|
||||
if not isinstance(price, int | float) or price <= 0:
|
||||
price = extract_tick_price(tick, "ask" if side == "BUY" else "bid")
|
||||
if price is None:
|
||||
msg = f"Tick price is unavailable for {symbol!r}."
|
||||
raise Mt5TradingError(msg)
|
||||
request = {
|
||||
@@ -986,7 +1261,7 @@ def place_market_order(
|
||||
"type": (
|
||||
client.mt5.ORDER_TYPE_BUY if side == "BUY" else client.mt5.ORDER_TYPE_SELL
|
||||
),
|
||||
"price": float(price),
|
||||
"price": price,
|
||||
"type_filling": _resolve_mt5_constant(
|
||||
client.mt5,
|
||||
"ORDER_FILLING",
|
||||
@@ -1083,6 +1358,125 @@ def close_open_positions(
|
||||
return results
|
||||
|
||||
|
||||
def _symbol_digits(client: Mt5TradingClient, symbol: str) -> int | None:
|
||||
try:
|
||||
raw_digits = get_symbol_snapshot(client, symbol).get("digits")
|
||||
if raw_digits is None:
|
||||
return None
|
||||
digits = int(raw_digits)
|
||||
except (AttributeError, TypeError, ValueError):
|
||||
return None
|
||||
return digits if digits >= 0 else None
|
||||
|
||||
|
||||
def _position_ticket(value: object) -> int | None:
|
||||
ticket = _optional_int(value)
|
||||
return ticket if ticket is not None and ticket > 0 else None
|
||||
|
||||
|
||||
def _current_stop_loss(value: object) -> float | None:
|
||||
return _optional_price(value)
|
||||
|
||||
|
||||
def _trailing_stop_loss(
|
||||
client: Mt5TradingClient,
|
||||
*,
|
||||
position_type: object,
|
||||
current_sl: float | None,
|
||||
bid: float | None,
|
||||
ask: float | None,
|
||||
digits: int,
|
||||
trailing_stop_ratio: float,
|
||||
) -> float | None:
|
||||
next_sl: float | None = None
|
||||
if position_type == client.mt5.POSITION_TYPE_BUY:
|
||||
if bid is not None:
|
||||
next_sl = round(bid * (1.0 - trailing_stop_ratio), digits)
|
||||
if current_sl is not None and current_sl >= next_sl:
|
||||
next_sl = None
|
||||
elif position_type == client.mt5.POSITION_TYPE_SELL and ask is not None:
|
||||
next_sl = round(ask * (1.0 + trailing_stop_ratio), digits)
|
||||
if current_sl is not None and current_sl <= next_sl:
|
||||
next_sl = None
|
||||
return next_sl
|
||||
|
||||
|
||||
def calculate_trailing_stop_updates(
|
||||
client: Mt5TradingClient,
|
||||
*,
|
||||
symbol: str,
|
||||
trailing_stop_ratio: float,
|
||||
) -> dict[int, float]:
|
||||
"""Return per-ticket trailing stop-loss updates for open symbol positions.
|
||||
|
||||
Buy positions trail from bid using ``bid * (1 - trailing_stop_ratio)``.
|
||||
Sell positions trail from ask using ``ask * (1 + trailing_stop_ratio)``.
|
||||
Existing stop losses are preserved when they are already more favorable.
|
||||
Missing symbol metadata returns an empty update map. Positions with a
|
||||
missing side-specific tick price are skipped.
|
||||
"""
|
||||
_require_protective_ratio(trailing_stop_ratio, "trailing_stop_ratio")
|
||||
positions = get_positions_frame(client, symbol=symbol)
|
||||
if positions.empty:
|
||||
return {}
|
||||
tick = get_tick_snapshot(client, symbol)
|
||||
bid = extract_tick_price(tick, "bid")
|
||||
ask = extract_tick_price(tick, "ask")
|
||||
digits = _symbol_digits(client, symbol)
|
||||
if digits is None:
|
||||
return {}
|
||||
|
||||
updates: dict[int, float] = {}
|
||||
for row in positions.to_dict("records"):
|
||||
ticket = _position_ticket(row.get("ticket"))
|
||||
if ticket is None:
|
||||
continue
|
||||
next_sl = _trailing_stop_loss(
|
||||
client,
|
||||
position_type=row.get("type"),
|
||||
current_sl=_current_stop_loss(row.get("sl")),
|
||||
bid=bid,
|
||||
ask=ask,
|
||||
digits=digits,
|
||||
trailing_stop_ratio=trailing_stop_ratio,
|
||||
)
|
||||
if next_sl is None:
|
||||
continue
|
||||
updates[ticket] = next_sl
|
||||
return updates
|
||||
|
||||
|
||||
def update_trailing_stop_loss_for_open_positions(
|
||||
client: Mt5TradingClient,
|
||||
*,
|
||||
symbol: str,
|
||||
trailing_stop_ratio: float,
|
||||
dry_run: bool = False,
|
||||
) -> list[OrderExecutionResult]:
|
||||
"""Update open positions whose trailing stop loss should move favorably.
|
||||
|
||||
Returns:
|
||||
Normalized execution results for positions that need an SL update.
|
||||
"""
|
||||
updates = calculate_trailing_stop_updates(
|
||||
client,
|
||||
symbol=symbol,
|
||||
trailing_stop_ratio=trailing_stop_ratio,
|
||||
)
|
||||
results: list[OrderExecutionResult] = []
|
||||
for ticket, stop_loss in updates.items():
|
||||
results.extend(
|
||||
update_sltp_for_open_positions(
|
||||
client,
|
||||
symbol=symbol,
|
||||
tickets=[ticket],
|
||||
stop_loss=stop_loss,
|
||||
dry_run=dry_run,
|
||||
),
|
||||
)
|
||||
return results
|
||||
|
||||
|
||||
def update_sltp_for_open_positions(
|
||||
client: Mt5TradingClient,
|
||||
*,
|
||||
@@ -1168,19 +1562,10 @@ def fetch_latest_closed_rates_for_trading_client(
|
||||
msg = "count must be positive."
|
||||
raise ValueError(msg)
|
||||
fetch_method = getattr(client, "fetch_latest_rates_as_df", None)
|
||||
if callable(fetch_method):
|
||||
fetched = fetch_method(symbol, granularity, count + 1)
|
||||
else:
|
||||
copy_method = getattr(client, "copy_rates_from_pos_as_df", None)
|
||||
if not callable(copy_method):
|
||||
msg = "MT5 trading client cannot fetch rate data."
|
||||
raise Mt5TradingError(msg)
|
||||
fetched = copy_method(
|
||||
symbol=symbol,
|
||||
timeframe=parse_timeframe(granularity),
|
||||
start_pos=0,
|
||||
count=count + 1,
|
||||
)
|
||||
if not callable(fetch_method):
|
||||
msg = "MT5 trading client cannot fetch rate data."
|
||||
raise Mt5TradingError(msg)
|
||||
fetched = fetch_method(symbol, granularity, count + 1)
|
||||
if not isinstance(fetched, pd.DataFrame):
|
||||
msg = (
|
||||
f"Malformed rate data for {symbol!r} at granularity {granularity!r}: "
|
||||
@@ -1202,6 +1587,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,
|
||||
|
||||
+1
-2
@@ -1,6 +1,6 @@
|
||||
[project]
|
||||
name = "mt5cli"
|
||||
version = "0.8.3"
|
||||
version = "0.9.6"
|
||||
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
|
||||
|
||||
@@ -740,6 +740,306 @@ class TestCommands:
|
||||
assert "must be a JSON object" in normalize_cli_output(result.output)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# close-positions command
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def _build_mock_trading_client() -> MagicMock:
|
||||
"""Return a MagicMock Mt5TradingClient with trading constants set."""
|
||||
client = MagicMock()
|
||||
client.mt5.POSITION_TYPE_BUY = 0
|
||||
client.mt5.POSITION_TYPE_SELL = 1
|
||||
client.mt5.ORDER_TYPE_BUY = 10
|
||||
client.mt5.ORDER_TYPE_SELL = 11
|
||||
client.mt5.TRADE_ACTION_DEAL = 20
|
||||
client.mt5.ORDER_FILLING_IOC = 30
|
||||
client.mt5.ORDER_TIME_GTC = 40
|
||||
client.mt5.TRADE_RETCODE_DONE = 10009
|
||||
client.mt5.TRADE_RETCODE_PLACED = 10008
|
||||
client.mt5.TRADE_RETCODE_DONE_PARTIAL = 10010
|
||||
return client
|
||||
|
||||
|
||||
class TestClosePositions:
|
||||
"""Tests for the close-positions command."""
|
||||
|
||||
@pytest.fixture
|
||||
def trading_client(self, mocker: MockerFixture) -> MagicMock:
|
||||
"""Patch create_trading_client and return a mock trading client."""
|
||||
client = _build_mock_trading_client()
|
||||
client.positions_get_as_df.return_value = pd.DataFrame([
|
||||
{"ticket": 1, "symbol": "JP225", "type": 0, "volume": 1.0},
|
||||
{"ticket": 2, "symbol": "EURUSD", "type": 1, "volume": 0.5},
|
||||
])
|
||||
client.symbol_info_tick_as_dict.return_value = {"ask": 1.2, "bid": 1.1}
|
||||
mocker.patch("mt5cli.cli.create_trading_client", return_value=client)
|
||||
return client
|
||||
|
||||
def test_dry_run_does_not_require_yes(
|
||||
self,
|
||||
tmp_path: Path,
|
||||
trading_client: MagicMock,
|
||||
) -> None:
|
||||
"""Test --dry-run mode succeeds without --yes."""
|
||||
output = tmp_path / "close.json"
|
||||
result = runner.invoke(
|
||||
app,
|
||||
["-o", str(output), "close-positions", "--symbol", "JP225", "--dry-run"],
|
||||
)
|
||||
assert result.exit_code == 0, result.output
|
||||
assert output.exists()
|
||||
trading_client.order_send.assert_not_called()
|
||||
trading_client.shutdown.assert_called_once()
|
||||
|
||||
def test_live_requires_yes(
|
||||
self,
|
||||
tmp_path: Path,
|
||||
trading_client: MagicMock,
|
||||
) -> None:
|
||||
"""Test live close-positions fails without --yes."""
|
||||
output = tmp_path / "close.json"
|
||||
result = runner.invoke(
|
||||
app,
|
||||
["-o", str(output), "close-positions", "--symbol", "JP225"],
|
||||
)
|
||||
assert result.exit_code != 0
|
||||
assert "Pass --yes" in normalize_cli_output(result.output)
|
||||
trading_client.order_send.assert_not_called()
|
||||
|
||||
def test_live_with_yes_calls_order_send(
|
||||
self,
|
||||
tmp_path: Path,
|
||||
trading_client: MagicMock,
|
||||
) -> None:
|
||||
"""Test --yes triggers live execution for matching positions."""
|
||||
trading_client.order_send.return_value = {"retcode": 10009, "comment": "ok"}
|
||||
output = tmp_path / "close.json"
|
||||
result = runner.invoke(
|
||||
app,
|
||||
["-o", str(output), "close-positions", "--symbol", "JP225", "--yes"],
|
||||
)
|
||||
assert result.exit_code == 0, result.output
|
||||
trading_client.order_send.assert_called_once()
|
||||
trading_client.shutdown.assert_called_once()
|
||||
|
||||
def test_symbol_filter_passed_through(
|
||||
self,
|
||||
tmp_path: Path,
|
||||
trading_client: MagicMock,
|
||||
) -> None:
|
||||
"""Test --symbol values are used to filter positions."""
|
||||
output = tmp_path / "close.json"
|
||||
result = runner.invoke(
|
||||
app,
|
||||
[
|
||||
"-o",
|
||||
str(output),
|
||||
"close-positions",
|
||||
"--symbol",
|
||||
"JP225",
|
||||
"--dry-run",
|
||||
],
|
||||
)
|
||||
assert result.exit_code == 0, result.output
|
||||
data = json.loads(output.read_text())
|
||||
assert len(data) == 1
|
||||
assert data[0]["symbol"] == "JP225"
|
||||
trading_client.shutdown.assert_called_once()
|
||||
|
||||
def test_multiple_symbols_filter(
|
||||
self,
|
||||
tmp_path: Path,
|
||||
trading_client: MagicMock,
|
||||
) -> None:
|
||||
"""Test multiple --symbol options are combined."""
|
||||
output = tmp_path / "close.json"
|
||||
result = runner.invoke(
|
||||
app,
|
||||
[
|
||||
"-o",
|
||||
str(output),
|
||||
"close-positions",
|
||||
"--symbol",
|
||||
"JP225",
|
||||
"--symbol",
|
||||
"EURUSD",
|
||||
"--dry-run",
|
||||
],
|
||||
)
|
||||
assert result.exit_code == 0, result.output
|
||||
data = json.loads(output.read_text())
|
||||
assert len(data) == 2
|
||||
symbols = {row["symbol"] for row in data}
|
||||
assert symbols == {"JP225", "EURUSD"}
|
||||
trading_client.shutdown.assert_called_once()
|
||||
|
||||
def test_ticket_filter_passed_through(
|
||||
self,
|
||||
tmp_path: Path,
|
||||
trading_client: MagicMock,
|
||||
) -> None:
|
||||
"""Test --ticket values are used to filter positions."""
|
||||
output = tmp_path / "close.json"
|
||||
result = runner.invoke(
|
||||
app,
|
||||
[
|
||||
"-o",
|
||||
str(output),
|
||||
"close-positions",
|
||||
"--ticket",
|
||||
"2",
|
||||
"--dry-run",
|
||||
],
|
||||
)
|
||||
assert result.exit_code == 0, result.output
|
||||
data = json.loads(output.read_text())
|
||||
assert len(data) == 1
|
||||
assert data[0]["symbol"] == "EURUSD"
|
||||
trading_client.shutdown.assert_called_once()
|
||||
|
||||
def test_symbol_and_ticket_combined(
|
||||
self,
|
||||
tmp_path: Path,
|
||||
trading_client: MagicMock,
|
||||
) -> None:
|
||||
"""Test --symbol and --ticket apply AND semantics when combined."""
|
||||
output = tmp_path / "close.json"
|
||||
result = runner.invoke(
|
||||
app,
|
||||
[
|
||||
"-o",
|
||||
str(output),
|
||||
"close-positions",
|
||||
"--symbol",
|
||||
"JP225",
|
||||
"--ticket",
|
||||
"1",
|
||||
"--dry-run",
|
||||
],
|
||||
)
|
||||
assert result.exit_code == 0, result.output
|
||||
data = json.loads(output.read_text())
|
||||
# symbol=JP225 AND ticket=1 → exactly one match
|
||||
assert len(data) == 1
|
||||
assert data[0]["symbol"] == "JP225"
|
||||
trading_client.shutdown.assert_called_once()
|
||||
|
||||
def test_missing_symbol_and_ticket_fails(
|
||||
self,
|
||||
tmp_path: Path,
|
||||
mocker: MockerFixture,
|
||||
) -> None:
|
||||
"""Test that omitting both --symbol and --ticket fails closed."""
|
||||
mocker.patch("mt5cli.cli.create_trading_client")
|
||||
output = tmp_path / "close.json"
|
||||
result = runner.invoke(
|
||||
app,
|
||||
["-o", str(output), "close-positions", "--dry-run"],
|
||||
)
|
||||
assert result.exit_code != 0
|
||||
assert "symbol" in normalize_cli_output(result.output).lower()
|
||||
|
||||
def test_output_export_dry_run(
|
||||
self,
|
||||
tmp_path: Path,
|
||||
trading_client: MagicMock,
|
||||
) -> None:
|
||||
"""Test dry-run results export with status=dry_run."""
|
||||
output = tmp_path / "close.json"
|
||||
result = runner.invoke(
|
||||
app,
|
||||
["-o", str(output), "close-positions", "--symbol", "JP225", "--dry-run"],
|
||||
)
|
||||
assert result.exit_code == 0, result.output
|
||||
trading_client.shutdown.assert_called_once()
|
||||
data = json.loads(output.read_text())
|
||||
assert data[0]["status"] == "dry_run"
|
||||
assert data[0]["dry_run"] is True
|
||||
assert data[0]["order_side"] == "SELL"
|
||||
|
||||
def test_order_send_unchanged(
|
||||
self,
|
||||
tmp_path: Path,
|
||||
mock_client: MagicMock,
|
||||
) -> None:
|
||||
"""Test that order-send behavior is unchanged by close-positions addition."""
|
||||
output = tmp_path / "out.csv"
|
||||
request = json.dumps({"action": 1, "symbol": "EURUSD", "volume": 0.1})
|
||||
result = runner.invoke(
|
||||
app,
|
||||
["-o", str(output), "order-send", "--request", request, "--yes"],
|
||||
)
|
||||
assert result.exit_code == 0, result.output
|
||||
mock_client.order_send_as_df.assert_called_once()
|
||||
|
||||
def test_shutdown_called_on_close_error(
|
||||
self,
|
||||
tmp_path: Path,
|
||||
mocker: MockerFixture,
|
||||
) -> None:
|
||||
"""Test that shutdown is called even when close_open_positions raises."""
|
||||
client = _build_mock_trading_client()
|
||||
client.positions_get_as_df.side_effect = RuntimeError("connection lost")
|
||||
mocker.patch("mt5cli.cli.create_trading_client", return_value=client)
|
||||
output = tmp_path / "close.json"
|
||||
result = runner.invoke(
|
||||
app,
|
||||
["-o", str(output), "close-positions", "--symbol", "JP225", "--dry-run"],
|
||||
)
|
||||
assert result.exit_code != 0
|
||||
client.shutdown.assert_called_once()
|
||||
|
||||
def test_dry_run_wins_over_yes(
|
||||
self,
|
||||
tmp_path: Path,
|
||||
trading_client: MagicMock,
|
||||
) -> None:
|
||||
"""Test that --dry-run takes precedence when combined with --yes."""
|
||||
output = tmp_path / "close.json"
|
||||
result = runner.invoke(
|
||||
app,
|
||||
[
|
||||
"-o",
|
||||
str(output),
|
||||
"close-positions",
|
||||
"--symbol",
|
||||
"JP225",
|
||||
"--dry-run",
|
||||
"--yes",
|
||||
],
|
||||
)
|
||||
assert result.exit_code == 0, result.output
|
||||
trading_client.order_send.assert_not_called()
|
||||
trading_client.shutdown.assert_called_once()
|
||||
|
||||
def test_no_matching_positions_exports_empty_result(
|
||||
self,
|
||||
tmp_path: Path,
|
||||
trading_client: MagicMock,
|
||||
) -> None:
|
||||
"""Test that zero filter matches produces an empty JSON array."""
|
||||
trading_client.positions_get_as_df.return_value = pd.DataFrame([
|
||||
{"ticket": 1, "symbol": "JP225", "type": 0, "volume": 1.0},
|
||||
])
|
||||
output = tmp_path / "close.json"
|
||||
result = runner.invoke(
|
||||
app,
|
||||
[
|
||||
"-o",
|
||||
str(output),
|
||||
"close-positions",
|
||||
"--symbol",
|
||||
"NONEXISTENT",
|
||||
"--dry-run",
|
||||
],
|
||||
)
|
||||
assert result.exit_code == 0, result.output
|
||||
trading_client.shutdown.assert_called_once()
|
||||
assert output.exists()
|
||||
assert json.loads(output.read_text()) == []
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Callback / shared options
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
+138
-40
@@ -2,9 +2,11 @@
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
import sqlite3
|
||||
from datetime import UTC, datetime
|
||||
from typing import TYPE_CHECKING, get_type_hints
|
||||
from pathlib import Path
|
||||
from typing import get_type_hints
|
||||
from unittest.mock import MagicMock
|
||||
|
||||
import pandas as pd
|
||||
@@ -15,7 +17,9 @@ from pytest_mock import MockerFixture # noqa: TC002
|
||||
import mt5cli
|
||||
from mt5cli import (
|
||||
DEDUP_KEYS,
|
||||
PUBLIC_EXPORT_TIERS,
|
||||
REQUIRED_COLUMNS,
|
||||
SECONDARY_PUBLIC_EXPORTS,
|
||||
STABLE_SDK_EXPORTS,
|
||||
TIME_COLUMNS,
|
||||
AccountSpec,
|
||||
@@ -33,8 +37,12 @@ from mt5cli import (
|
||||
RateTarget,
|
||||
build_config,
|
||||
build_rate_targets,
|
||||
calculate_account_projected_margin_ratio,
|
||||
calculate_margin_and_volume,
|
||||
calculate_positions_margin,
|
||||
calculate_projected_margin_ratio,
|
||||
calculate_symbol_group_margin_ratio,
|
||||
calculate_trailing_stop_updates,
|
||||
call_with_normalized_errors,
|
||||
detect_format,
|
||||
drop_forming_rate_bar,
|
||||
@@ -42,8 +50,10 @@ from mt5cli import (
|
||||
ensure_utc,
|
||||
export_dataframe,
|
||||
export_dataframe_to_sqlite,
|
||||
extract_tick_price,
|
||||
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,
|
||||
@@ -68,9 +78,6 @@ from mt5cli.history import create_rate_compatibility_views
|
||||
from mt5cli.retry import retry_with_backoff
|
||||
from mt5cli.schemas import ensure_utc_columns, normalize_time_columns
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
def _sample_frame(kind: DataKind) -> pd.DataFrame:
|
||||
if kind is DataKind.rates:
|
||||
@@ -227,16 +234,19 @@ def test_is_recoverable_mt5_error(exc: Exception) -> None:
|
||||
assert is_recoverable_mt5_error(exc)
|
||||
|
||||
|
||||
def test_normalize_mt5_exception_maps_types() -> None:
|
||||
@pytest.mark.parametrize(
|
||||
("exc", "expected_type"),
|
||||
[
|
||||
(Mt5RuntimeError("x"), Mt5ConnectionError),
|
||||
(Mt5TradingError("x"), Mt5OperationError),
|
||||
],
|
||||
)
|
||||
def test_normalize_mt5_exception_maps_types(
|
||||
exc: Exception,
|
||||
expected_type: type[Mt5ConnectionError | Mt5OperationError],
|
||||
) -> None:
|
||||
"""MT5 exceptions map to stable mt5cli types."""
|
||||
assert isinstance(
|
||||
normalize_mt5_exception(Mt5RuntimeError("x")),
|
||||
Mt5ConnectionError,
|
||||
)
|
||||
assert isinstance(
|
||||
normalize_mt5_exception(Mt5TradingError("x")),
|
||||
Mt5OperationError,
|
||||
)
|
||||
assert isinstance(normalize_mt5_exception(exc), expected_type)
|
||||
|
||||
|
||||
def test_call_with_normalized_errors_reraises_mapped_type() -> None:
|
||||
@@ -413,26 +423,24 @@ def test_normalize_time_columns_skips_absent_time_fields() -> None:
|
||||
assert list(result.columns) == ["open"]
|
||||
|
||||
|
||||
def test_normalize_time_columns_converts_unix_seconds() -> None:
|
||||
"""Numeric MT5 ``time`` values are interpreted as Unix seconds."""
|
||||
frame = pd.DataFrame({"time": [1704067200]})
|
||||
result = normalize_time_columns(frame, DataKind.rates)
|
||||
assert result.loc[0, "time"] == pd.Timestamp("2024-01-01T00:00:00+00:00")
|
||||
|
||||
|
||||
def test_normalize_time_columns_converts_unix_milliseconds() -> None:
|
||||
"""Numeric MT5 ``time_msc`` values are interpreted as Unix milliseconds."""
|
||||
frame = pd.DataFrame({"time_msc": [1704067200000]})
|
||||
result = normalize_time_columns(frame, DataKind.ticks)
|
||||
assert result.loc[0, "time_msc"] == pd.Timestamp("2024-01-01T00:00:00+00:00")
|
||||
|
||||
|
||||
def test_normalize_time_columns_preserves_utc_datetimes() -> None:
|
||||
"""Already-converted datetime values remain UTC-normalized."""
|
||||
aware = datetime(2024, 1, 1, tzinfo=UTC)
|
||||
frame = pd.DataFrame({"time": [aware]})
|
||||
result = normalize_time_columns(frame, DataKind.rates)
|
||||
assert result.loc[0, "time"] == pd.Timestamp("2024-01-01T00:00:00+00:00")
|
||||
@pytest.mark.parametrize(
|
||||
("col", "value", "kind"),
|
||||
[
|
||||
("time", 1704067200, DataKind.rates),
|
||||
("time_msc", 1704067200000, DataKind.ticks),
|
||||
("time", datetime(2024, 1, 1, tzinfo=UTC), DataKind.rates),
|
||||
("time", "2024-01-01T00:00:00+00:00", DataKind.rates),
|
||||
],
|
||||
)
|
||||
def test_normalize_time_columns_coerces_value(
|
||||
col: str,
|
||||
value: object,
|
||||
kind: DataKind,
|
||||
) -> None:
|
||||
"""Time column values are coerced to UTC timestamps regardless of input type."""
|
||||
frame = pd.DataFrame({col: [value]})
|
||||
result = normalize_time_columns(frame, kind)
|
||||
assert result.loc[0, col] == pd.Timestamp("2024-01-01T00:00:00+00:00")
|
||||
|
||||
|
||||
def test_normalize_time_columns_handles_optional_order_times() -> None:
|
||||
@@ -482,13 +490,6 @@ def test_ensure_utc_columns_skips_missing_columns() -> None:
|
||||
assert "time" in result.columns
|
||||
|
||||
|
||||
def test_normalize_time_columns_coerces_string_timestamps() -> None:
|
||||
"""String timestamps are parsed with timezone-aware datetime coercion."""
|
||||
frame = pd.DataFrame({"time": ["2024-01-01T00:00:00+00:00"]})
|
||||
result = normalize_time_columns(frame, DataKind.rates)
|
||||
assert result.loc[0, "time"] == pd.Timestamp("2024-01-01T00:00:00+00:00")
|
||||
|
||||
|
||||
def test_ensure_utc_columns_coerces_non_mt5_columns() -> None:
|
||||
"""Non-MT5 columns still coerce to UTC datetimes."""
|
||||
frame = pd.DataFrame({"created_at": ["2024-01-01T00:00:00+00:00"]})
|
||||
@@ -546,11 +547,69 @@ class TestStableSdkContract:
|
||||
missing = sorted(STABLE_SDK_EXPORTS - set(mt5cli.__all__))
|
||||
assert not missing, f"STABLE_SDK_EXPORTS missing from __all__: {missing}"
|
||||
|
||||
def test_public_export_tiers_are_disjoint_and_complete(self) -> None:
|
||||
"""Documented public tiers do not overlap and classify root exports."""
|
||||
assert PUBLIC_EXPORT_TIERS == {
|
||||
"stable": STABLE_SDK_EXPORTS,
|
||||
"secondary": SECONDARY_PUBLIC_EXPORTS,
|
||||
}
|
||||
assert not (STABLE_SDK_EXPORTS & SECONDARY_PUBLIC_EXPORTS)
|
||||
tiered_exports = STABLE_SDK_EXPORTS | SECONDARY_PUBLIC_EXPORTS
|
||||
root_exports = set(mt5cli.__all__)
|
||||
|
||||
missing_from_root = sorted(tiered_exports - root_exports)
|
||||
assert not missing_from_root, (
|
||||
f"Tiered exports missing from __all__: {missing_from_root}"
|
||||
)
|
||||
|
||||
tier_metadata_exports = {
|
||||
"PUBLIC_EXPORT_TIERS",
|
||||
"SECONDARY_PUBLIC_EXPORTS",
|
||||
"STABLE_SDK_EXPORTS",
|
||||
}
|
||||
unclassified_root_exports = sorted(
|
||||
root_exports - tiered_exports - tier_metadata_exports,
|
||||
)
|
||||
assert not unclassified_root_exports, (
|
||||
f"Root exports missing from public API tiers: {unclassified_root_exports}"
|
||||
)
|
||||
|
||||
def test_stable_docs_do_not_document_nonstable_exports(self) -> None:
|
||||
"""Stable docs do not promote secondary root exports."""
|
||||
docs_path = Path("docs/api/public-contract.md")
|
||||
docs = docs_path.read_text(encoding="utf-8")
|
||||
stable_section = docs.split("## Stable downstream SDK API", maxsplit=1)[
|
||||
1
|
||||
].split(
|
||||
"## Secondary public exports",
|
||||
maxsplit=1,
|
||||
)[0]
|
||||
documented_symbols = set(
|
||||
re.findall(r"`([A-Za-z_][A-Za-z0-9_]*)`", stable_section)
|
||||
)
|
||||
nonstable_exports = SECONDARY_PUBLIC_EXPORTS
|
||||
|
||||
wrongly_stable = sorted(documented_symbols & nonstable_exports)
|
||||
assert not wrongly_stable, (
|
||||
f"Non-stable exports documented in stable section: {wrongly_stable}"
|
||||
)
|
||||
|
||||
@pytest.mark.parametrize("name", sorted(STABLE_SDK_EXPORTS))
|
||||
def test_stable_exports_are_importable_from_package_root(self, name: str) -> None:
|
||||
"""Stable SDK names resolve through ``from mt5cli import ...``."""
|
||||
assert hasattr(mt5cli, name), f"{name!r} missing from mt5cli package root"
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"name",
|
||||
sorted(SECONDARY_PUBLIC_EXPORTS),
|
||||
)
|
||||
def test_secondary_exports_are_importable(
|
||||
self,
|
||||
name: str,
|
||||
) -> None:
|
||||
"""Non-stable public names remain available from the package root."""
|
||||
assert hasattr(mt5cli, name), f"{name!r} missing from mt5cli package root"
|
||||
|
||||
def test_drop_forming_rate_bar_from_package_root(self) -> None:
|
||||
"""Closed-bar trimming is available from the stable package surface."""
|
||||
frame = pd.DataFrame({"time": [1, 2, 3], "close": [1.0, 1.1, 1.2]})
|
||||
@@ -614,6 +673,16 @@ class TestStableSdkContract:
|
||||
|
||||
assert calculate_positions_margin(client) == 0
|
||||
|
||||
def test_generic_trading_helpers_from_package_root(self) -> None:
|
||||
"""New generic trading helpers resolve through the stable surface."""
|
||||
price = extract_tick_price({"bid": "1.2"}, "bid")
|
||||
assert price is not None
|
||||
assert abs(price - 1.2) < 1e-9
|
||||
assert callable(calculate_trailing_stop_updates)
|
||||
assert callable(calculate_account_projected_margin_ratio)
|
||||
assert callable(calculate_projected_margin_ratio)
|
||||
assert callable(calculate_symbol_group_margin_ratio)
|
||||
|
||||
def test_resolve_rate_view_name_from_package_root(self, tmp_path: Path) -> None:
|
||||
"""Rate view resolution is importable and honors require_existing."""
|
||||
db_path = tmp_path / "rates.db"
|
||||
@@ -734,3 +803,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
|
||||
|
||||
+19
-54
@@ -705,19 +705,25 @@ class TestIncrementalStart:
|
||||
assert starts["EURUSD", 1] == datetime(2024, 1, 2, tzinfo=UTC)
|
||||
assert starts["GBPUSD", 1] == datetime(2024, 1, 3, tzinfo=UTC)
|
||||
|
||||
def test_load_incremental_start_datetimes_requires_timeframe_column(
|
||||
@pytest.mark.parametrize(
|
||||
("ddl", "missing_col"),
|
||||
[
|
||||
("CREATE TABLE rates(symbol TEXT, time TEXT, open REAL)", "timeframe"),
|
||||
("CREATE TABLE rates(timeframe INTEGER, time TEXT, open REAL)", "symbol"),
|
||||
("CREATE TABLE rates(symbol TEXT, timeframe INTEGER, open REAL)", "time"),
|
||||
],
|
||||
)
|
||||
def test_load_incremental_start_datetimes_requires_column(
|
||||
self,
|
||||
tmp_path: Path,
|
||||
ddl: str,
|
||||
missing_col: str,
|
||||
) -> None:
|
||||
"""Test rates tables without timeframe fail fast during incremental resume."""
|
||||
"""Test rates tables missing a required column fail fast."""
|
||||
fallback = datetime(2024, 1, 1, tzinfo=UTC)
|
||||
with sqlite3.connect(tmp_path / "rates-without-timeframe.db") as conn:
|
||||
conn.execute("CREATE TABLE rates(symbol TEXT, time TEXT, open REAL)")
|
||||
conn.execute(
|
||||
"INSERT INTO rates(symbol, time, open) VALUES (?, ?, ?)",
|
||||
("EURUSD", "2024-01-02T00:00:00+00:00", 1.0),
|
||||
)
|
||||
with pytest.raises(ValueError, match="missing: timeframe") as exc_info:
|
||||
with sqlite3.connect(tmp_path / f"rates-no-{missing_col}.db") as conn:
|
||||
conn.execute(ddl)
|
||||
with pytest.raises(ValueError, match=f"missing: {missing_col}") as exc_info:
|
||||
load_incremental_start_datetimes(
|
||||
conn,
|
||||
Dataset.rates,
|
||||
@@ -725,47 +731,7 @@ class TestIncrementalStart:
|
||||
timeframes=[1],
|
||||
fallback_start=fallback,
|
||||
)
|
||||
assert "timeframe" in str(exc_info.value)
|
||||
|
||||
def test_load_incremental_start_datetimes_requires_symbol_column(
|
||||
self,
|
||||
tmp_path: Path,
|
||||
) -> None:
|
||||
"""Test rates tables without symbol fail fast during incremental resume."""
|
||||
fallback = datetime(2024, 1, 1, tzinfo=UTC)
|
||||
with sqlite3.connect(tmp_path / "rates-no-symbol.db") as conn:
|
||||
conn.execute(
|
||||
"CREATE TABLE rates(timeframe INTEGER, time TEXT, open REAL)",
|
||||
)
|
||||
with pytest.raises(ValueError, match="missing: symbol") as exc_info:
|
||||
load_incremental_start_datetimes(
|
||||
conn,
|
||||
Dataset.rates,
|
||||
symbols=["EURUSD"],
|
||||
timeframes=[1],
|
||||
fallback_start=fallback,
|
||||
)
|
||||
assert "symbol" in str(exc_info.value)
|
||||
|
||||
def test_load_incremental_start_datetimes_requires_time_column(
|
||||
self,
|
||||
tmp_path: Path,
|
||||
) -> None:
|
||||
"""Test rates tables without time fail fast during incremental resume."""
|
||||
fallback = datetime(2024, 1, 1, tzinfo=UTC)
|
||||
with sqlite3.connect(tmp_path / "rates-no-time.db") as conn:
|
||||
conn.execute(
|
||||
"CREATE TABLE rates(symbol TEXT, timeframe INTEGER, open REAL)",
|
||||
)
|
||||
with pytest.raises(ValueError, match="missing: time") as exc_info:
|
||||
load_incremental_start_datetimes(
|
||||
conn,
|
||||
Dataset.rates,
|
||||
symbols=["EURUSD"],
|
||||
timeframes=[1],
|
||||
fallback_start=fallback,
|
||||
)
|
||||
assert "time" in str(exc_info.value)
|
||||
assert missing_col in str(exc_info.value)
|
||||
|
||||
def test_load_incremental_start_datetimes_rejects_unrelated_rates_columns(
|
||||
self,
|
||||
@@ -1800,12 +1766,11 @@ class TestIncrementalIntegration:
|
||||
)
|
||||
assert written_tables == set()
|
||||
|
||||
def test_resolve_history_tick_flags_invalid(self) -> None:
|
||||
@pytest.mark.parametrize("flags", ["BAD", 7])
|
||||
def test_resolve_history_tick_flags_invalid(self, flags: str | int) -> None:
|
||||
"""Test invalid tick flags raise ValueError."""
|
||||
with pytest.raises(ValueError, match="Invalid tick flags"):
|
||||
resolve_history_tick_flags("BAD")
|
||||
with pytest.raises(ValueError, match="Invalid tick flags"):
|
||||
resolve_history_tick_flags(7)
|
||||
resolve_history_tick_flags(flags)
|
||||
|
||||
def test_resolve_history_timeframes_invalid(self) -> None:
|
||||
"""Test invalid timeframes raise ValueError."""
|
||||
|
||||
@@ -54,6 +54,7 @@ from mt5cli.sdk import (
|
||||
resolve_account_spec,
|
||||
resolve_account_specs,
|
||||
substitute_env_placeholders,
|
||||
substitute_mapping_values,
|
||||
symbol_info,
|
||||
symbol_info_tick,
|
||||
symbols,
|
||||
@@ -1777,6 +1778,80 @@ class TestSubstituteEnvPlaceholders:
|
||||
with pytest.raises(ValueError, match="'MT5_MISSING' is not set"):
|
||||
substitute_env_placeholders("${MT5_MISSING}")
|
||||
|
||||
def test_whole_dollar_not_substituted_by_default(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
"""Test $ENV_NAME is not expanded without allow_whole_dollar_env=True."""
|
||||
monkeypatch.setenv("MT5_PASSWORD", "secret")
|
||||
|
||||
assert substitute_env_placeholders("$MT5_PASSWORD") == "$MT5_PASSWORD"
|
||||
|
||||
def test_whole_dollar_substituted_with_opt_in(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
"""Test $ENV_NAME is expanded when allow_whole_dollar_env=True."""
|
||||
monkeypatch.setenv("MT5_PASSWORD", "secret")
|
||||
|
||||
result = substitute_env_placeholders(
|
||||
"$MT5_PASSWORD", allow_whole_dollar_env=True
|
||||
)
|
||||
|
||||
assert result == "secret"
|
||||
|
||||
def test_whole_dollar_missing_variable_raises_value_error(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
"""Test missing $ENV_NAME raises ValueError when opt-in is enabled."""
|
||||
monkeypatch.delenv("MT5_MISSING", raising=False)
|
||||
|
||||
with pytest.raises(ValueError, match="'MT5_MISSING' is not set"):
|
||||
substitute_env_placeholders("$MT5_MISSING", allow_whole_dollar_env=True)
|
||||
|
||||
def test_partial_dollar_not_expanded_with_opt_in(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
"""Test $ENV embedded in a larger string is not expanded."""
|
||||
monkeypatch.setenv("pass", "secret")
|
||||
monkeypatch.setenv("ENV", "val")
|
||||
|
||||
assert (
|
||||
substitute_env_placeholders("plan$pass", allow_whole_dollar_env=True)
|
||||
== "plan$pass"
|
||||
)
|
||||
assert (
|
||||
substitute_env_placeholders("abc$ENV", allow_whole_dollar_env=True)
|
||||
== "abc$ENV"
|
||||
)
|
||||
|
||||
def test_dollar_with_suffix_not_expanded_with_opt_in(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
"""Test $ENV-suffix is not expanded (not a whole-value placeholder)."""
|
||||
monkeypatch.setenv("ENV", "val")
|
||||
|
||||
assert (
|
||||
substitute_env_placeholders("$ENV-suffix", allow_whole_dollar_env=True)
|
||||
== "$ENV-suffix"
|
||||
)
|
||||
|
||||
def test_brace_format_works_with_opt_in(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
"""Test ${ENV_VAR} substitution still works when allow_whole_dollar_env=True."""
|
||||
monkeypatch.setenv("MT5_LOGIN", "12345")
|
||||
|
||||
result = substitute_env_placeholders(
|
||||
"${MT5_LOGIN}", allow_whole_dollar_env=True
|
||||
)
|
||||
|
||||
assert result == "12345"
|
||||
|
||||
|
||||
class TestResolveAccountSpec:
|
||||
"""Tests for resolve_account_spec and resolve_account_specs."""
|
||||
@@ -1863,6 +1938,105 @@ class TestResolveAccountSpec:
|
||||
assert [a.server for a in resolved] == ["Shared", "Fixed"]
|
||||
assert all(a.timeout == 1000 for a in resolved)
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("allow_whole_dollar_env", "expected"),
|
||||
[
|
||||
(True, "secret"),
|
||||
(False, "$MT5_PASSWORD"),
|
||||
],
|
||||
)
|
||||
def test_resolve_account_spec_whole_dollar_password(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
allow_whole_dollar_env: bool,
|
||||
expected: str,
|
||||
) -> None:
|
||||
"""Test resolve_account_spec expands $ENV_NAME password only with opt-in."""
|
||||
monkeypatch.setenv("MT5_PASSWORD", "secret")
|
||||
account = AccountSpec(symbols=["EURUSD"], password="$MT5_PASSWORD")
|
||||
|
||||
resolved = resolve_account_spec(
|
||||
account, allow_whole_dollar_env=allow_whole_dollar_env
|
||||
)
|
||||
|
||||
assert resolved.password == expected
|
||||
|
||||
def test_resolve_account_specs_with_whole_dollar_env(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
"""Test resolve_account_specs threads allow_whole_dollar_env to each account."""
|
||||
monkeypatch.setenv("MT5_SERVER", "Broker-Demo")
|
||||
accounts = [
|
||||
AccountSpec(symbols=["EURUSD"], server="$MT5_SERVER"),
|
||||
AccountSpec(symbols=["GBPUSD"], server="Fixed"),
|
||||
]
|
||||
|
||||
resolved = resolve_account_specs(accounts, allow_whole_dollar_env=True)
|
||||
|
||||
assert resolved[0].server == "Broker-Demo"
|
||||
assert resolved[1].server == "Fixed"
|
||||
|
||||
def test_resolve_account_spec_whole_dollar_login(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
"""Test $ENV_NAME login string is expanded when allow_whole_dollar_env=True."""
|
||||
monkeypatch.setenv("MT5_LOGIN", "12345")
|
||||
account = AccountSpec(symbols=["EURUSD"], login="$MT5_LOGIN")
|
||||
|
||||
resolved = resolve_account_spec(account, allow_whole_dollar_env=True)
|
||||
|
||||
assert resolved.login == "12345"
|
||||
|
||||
|
||||
class TestBuildConfigWholeDollarEnv:
|
||||
"""Tests for build_config with allow_whole_dollar_env."""
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("env_var", "field", "env_value"),
|
||||
[
|
||||
("MT5_SERVER", "server", "Broker-Demo"),
|
||||
("MT5_PASSWORD", "password", "secret"),
|
||||
("MT5_PATH", "path", "/opt/mt5/terminal64.exe"),
|
||||
],
|
||||
)
|
||||
def test_build_config_substitutes_field_with_opt_in(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
env_var: str,
|
||||
field: str,
|
||||
env_value: str,
|
||||
) -> None:
|
||||
"""Test build_config expands $ENV_NAME fields when opt-in is enabled."""
|
||||
monkeypatch.setenv(env_var, env_value)
|
||||
|
||||
config = build_config(**{field: f"${env_var}"}, allow_whole_dollar_env=True) # type: ignore[arg-type]
|
||||
|
||||
assert getattr(config, field) == env_value
|
||||
|
||||
def test_build_config_leaves_dollar_literal_by_default(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
"""Test build_config does not substitute $ENV without opt-in."""
|
||||
monkeypatch.setenv("MT5_SERVER", "Broker-Demo")
|
||||
|
||||
config = build_config(server="$MT5_SERVER")
|
||||
|
||||
assert config.server == "$MT5_SERVER"
|
||||
|
||||
def test_build_config_none_params_not_substituted(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch, # noqa: ARG002
|
||||
) -> None:
|
||||
"""Test build_config with None params does not raise even with opt-in."""
|
||||
config = build_config(allow_whole_dollar_env=True)
|
||||
|
||||
assert config.server is None
|
||||
assert config.password is None
|
||||
assert config.path is None
|
||||
|
||||
|
||||
class TestThrottledHistoryUpdater:
|
||||
"""Tests for the throttled incremental history updater."""
|
||||
@@ -2251,3 +2425,263 @@ class TestThrottledHistoryUpdater:
|
||||
updater.update(MagicMock(), ["EURUSD"])
|
||||
|
||||
assert updater.last_update_monotonic is None
|
||||
|
||||
|
||||
class TestBuildConfigStringLogin:
|
||||
"""Tests for build_config() string login coercion (issue #61)."""
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("login", "expected"),
|
||||
[
|
||||
(None, None),
|
||||
(12345, 12345),
|
||||
("12345", 12345),
|
||||
(" 12345 ", 12345),
|
||||
("", None),
|
||||
(" ", None),
|
||||
],
|
||||
)
|
||||
def test_coerces_login_from_string(
|
||||
self,
|
||||
login: int | str | None,
|
||||
expected: int | None,
|
||||
) -> None:
|
||||
"""Test build_config coerces string login to int or None."""
|
||||
config = build_config(login=login)
|
||||
assert config.login == expected
|
||||
|
||||
def test_rejects_non_numeric_string_login(self) -> None:
|
||||
"""Test build_config raises ValueError for non-numeric string login."""
|
||||
with pytest.raises(ValueError, match="invalid literal"):
|
||||
build_config(login="abc")
|
||||
|
||||
def test_expands_dollar_brace_login_with_opt_in(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
"""Test build_config expands ${MT5_LOGIN} and coerces with opt-in."""
|
||||
monkeypatch.setenv("MT5_LOGIN", "12345")
|
||||
config = build_config(login="${MT5_LOGIN}", allow_whole_dollar_env=True)
|
||||
assert config.login == 12345
|
||||
|
||||
def test_expands_whole_dollar_login_with_opt_in(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
"""Test build_config expands $MT5_LOGIN and coerces with opt-in."""
|
||||
monkeypatch.setenv("MT5_LOGIN", "99999")
|
||||
config = build_config(login="$MT5_LOGIN", allow_whole_dollar_env=True)
|
||||
assert config.login == 99999
|
||||
|
||||
def test_missing_env_variable_raises(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
"""Test build_config raises ValueError when referenced env var is not set."""
|
||||
monkeypatch.delenv("MT5_LOGIN", raising=False)
|
||||
with pytest.raises(ValueError, match="'MT5_LOGIN' is not set"):
|
||||
build_config(login="${MT5_LOGIN}", allow_whole_dollar_env=True)
|
||||
|
||||
def test_env_expands_to_blank_becomes_none(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
"""Test build_config coerces blank env-expanded login to None."""
|
||||
monkeypatch.setenv("MT5_LOGIN", "")
|
||||
config = build_config(login="${MT5_LOGIN}", allow_whole_dollar_env=True)
|
||||
assert config.login is None
|
||||
|
||||
def test_dollar_brace_login_not_expanded_without_opt_in(self) -> None:
|
||||
"""Test ${MT5_LOGIN} is not expanded when allow_whole_dollar_env=False."""
|
||||
with pytest.raises(ValueError, match="invalid literal"):
|
||||
build_config(login="${MT5_LOGIN}")
|
||||
|
||||
def test_integer_login_preserved_backward_compat(self) -> None:
|
||||
"""Test existing int login callers remain backward-compatible."""
|
||||
config = build_config(login=54321)
|
||||
assert config.login == 54321
|
||||
|
||||
def test_none_login_preserved_backward_compat(self) -> None:
|
||||
"""Test existing None login callers remain backward-compatible."""
|
||||
config = build_config(login=None)
|
||||
assert config.login is None
|
||||
|
||||
|
||||
class TestSubstituteMappingValues:
|
||||
"""Tests for substitute_mapping_values() (issue #62)."""
|
||||
|
||||
def test_substitutes_selected_keys_in_flat_dict(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
"""Test selected keys are substituted in a flat mapping."""
|
||||
monkeypatch.setenv("MT5_LOGIN", "12345")
|
||||
data: dict[str, object] = {
|
||||
"mt5_login": "${MT5_LOGIN}",
|
||||
"strategy_name": "${MT5_LOGIN}",
|
||||
}
|
||||
result = substitute_mapping_values(data, keys={"mt5_login"})
|
||||
assert result == {"mt5_login": "12345", "strategy_name": "${MT5_LOGIN}"}
|
||||
|
||||
def test_preserves_non_selected_literal_dollar_signs(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
"""Test literal dollar signs in non-selected fields are preserved exactly."""
|
||||
monkeypatch.setenv("MT5_PASSWORD", "secret")
|
||||
data: dict[str, object] = {
|
||||
"mt5_password": "${MT5_PASSWORD}",
|
||||
"notes": "$NOT_EXPANDED",
|
||||
}
|
||||
result = substitute_mapping_values(data, keys={"mt5_password"})
|
||||
assert result == {"mt5_password": "secret", "notes": "$NOT_EXPANDED"}
|
||||
|
||||
def test_nested_dict_traversal_substitutes_selected_keys(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
"""Test selected keys inside nested dicts are substituted."""
|
||||
monkeypatch.setenv("MT5_SERVER", "Broker-Demo")
|
||||
data: dict[str, object] = {
|
||||
"outer": {
|
||||
"mt5_server": "${MT5_SERVER}",
|
||||
"other": "${MT5_SERVER}",
|
||||
}
|
||||
}
|
||||
result = substitute_mapping_values(data, keys={"mt5_server"})
|
||||
assert result == {
|
||||
"outer": {"mt5_server": "Broker-Demo", "other": "${MT5_SERVER}"}
|
||||
}
|
||||
|
||||
def test_nested_list_traversal_substitutes_selected_keys(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
"""Test selected keys inside list elements are substituted."""
|
||||
monkeypatch.setenv("MT5_LOGIN", "42")
|
||||
data: dict[str, object] = {
|
||||
"accounts": [
|
||||
{"mt5_login": "${MT5_LOGIN}", "name": "${MT5_LOGIN}"},
|
||||
{"mt5_login": "${MT5_LOGIN}", "name": "fixed"},
|
||||
]
|
||||
}
|
||||
result = substitute_mapping_values(data, keys={"mt5_login"})
|
||||
assert result == {
|
||||
"accounts": [
|
||||
{"mt5_login": "42", "name": "${MT5_LOGIN}"},
|
||||
{"mt5_login": "42", "name": "fixed"},
|
||||
]
|
||||
}
|
||||
|
||||
def test_whole_dollar_expanded_with_opt_in(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
"""Test $ENV_NAME is expanded when allow_whole_dollar_env=True."""
|
||||
monkeypatch.setenv("MT5_PASSWORD", "secret")
|
||||
data: dict[str, object] = {"mt5_password": "$MT5_PASSWORD"}
|
||||
result = substitute_mapping_values(
|
||||
data,
|
||||
keys={"mt5_password"},
|
||||
allow_whole_dollar_env=True,
|
||||
)
|
||||
assert result == {"mt5_password": "secret"}
|
||||
|
||||
def test_whole_dollar_not_expanded_by_default(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
"""Test $ENV_NAME in a selected key is preserved when opt-in is False."""
|
||||
monkeypatch.setenv("MT5_PASSWORD", "secret")
|
||||
data: dict[str, object] = {"mt5_password": "$MT5_PASSWORD"}
|
||||
result = substitute_mapping_values(data, keys={"mt5_password"})
|
||||
assert result == {"mt5_password": "$MT5_PASSWORD"}
|
||||
|
||||
def test_blank_string_becomes_none_for_blank_keys(self) -> None:
|
||||
"""Test blank strings are normalised to None for blank_string_keys_as_none."""
|
||||
data: dict[str, object] = {
|
||||
"mt5_login": "",
|
||||
"mt5_password": " ",
|
||||
"other": "",
|
||||
}
|
||||
result = substitute_mapping_values(
|
||||
data,
|
||||
keys=set(),
|
||||
blank_string_keys_as_none={"mt5_login", "mt5_password"},
|
||||
)
|
||||
assert result == {"mt5_login": None, "mt5_password": None, "other": ""}
|
||||
|
||||
def test_env_expanded_blank_becomes_none(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
"""Test env-expanded blank string is normalised to None."""
|
||||
monkeypatch.setenv("MT5_LOGIN", "")
|
||||
data: dict[str, object] = {"mt5_login": "${MT5_LOGIN}"}
|
||||
result = substitute_mapping_values(
|
||||
data,
|
||||
keys={"mt5_login"},
|
||||
blank_string_keys_as_none={"mt5_login"},
|
||||
)
|
||||
assert result == {"mt5_login": None}
|
||||
|
||||
def test_missing_env_variable_raises_for_selected_key(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
"""Test missing env var for a selected key raises ValueError."""
|
||||
monkeypatch.delenv("MT5_MISSING", raising=False)
|
||||
data: dict[str, object] = {"mt5_login": "${MT5_MISSING}"}
|
||||
with pytest.raises(ValueError, match="'MT5_MISSING' is not set"):
|
||||
substitute_mapping_values(data, keys={"mt5_login"})
|
||||
|
||||
def test_non_string_values_preserved(self) -> None:
|
||||
"""Test non-string values under selected or non-selected keys are preserved."""
|
||||
data: dict[str, object] = {
|
||||
"mt5_login": 12345,
|
||||
"timeout": 5000,
|
||||
"enabled": True,
|
||||
"ratio": 1.5,
|
||||
"nothing": None,
|
||||
}
|
||||
result = substitute_mapping_values(
|
||||
data, keys={"mt5_login", "timeout", "enabled", "ratio", "nothing"}
|
||||
)
|
||||
assert result == data
|
||||
|
||||
def test_caller_supplied_key_set_substitutes_correctly(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
"""Test helper works with any caller-supplied key set."""
|
||||
monkeypatch.setenv("APP_LOGIN", "77777")
|
||||
monkeypatch.setenv("APP_PASSWORD", "p4ss")
|
||||
data: dict[str, object] = {
|
||||
"app_login": "${APP_LOGIN}",
|
||||
"app_password": "${APP_PASSWORD}",
|
||||
"unrelated": "${APP_LOGIN}",
|
||||
}
|
||||
credential_keys = {"app_login", "app_password"}
|
||||
result = substitute_mapping_values(data, keys=credential_keys)
|
||||
assert result == {
|
||||
"app_login": "77777",
|
||||
"app_password": "p4ss",
|
||||
"unrelated": "${APP_LOGIN}",
|
||||
}
|
||||
|
||||
def test_scalar_data_returned_unchanged(self) -> None:
|
||||
"""Test a scalar (non-dict, non-list) value is returned as-is."""
|
||||
assert substitute_mapping_values("hello", keys={"x"}) == "hello"
|
||||
assert substitute_mapping_values(42, keys={"x"}) == 42
|
||||
assert substitute_mapping_values(None, keys={"x"}) is None
|
||||
|
||||
def test_tuple_container_not_traversed(
|
||||
self,
|
||||
monkeypatch: pytest.MonkeyPatch,
|
||||
) -> None:
|
||||
"""Test tuple containers are returned as-is without traversal."""
|
||||
monkeypatch.setenv("MT5_LOGIN", "42")
|
||||
data: dict[str, object] = {"accounts": ({"mt5_login": "${MT5_LOGIN}"},)}
|
||||
result = substitute_mapping_values(data, keys={"mt5_login"})
|
||||
# tuple is returned as-is; inner dict is NOT visited
|
||||
assert result == {"accounts": ({"mt5_login": "${MT5_LOGIN}"},)}
|
||||
|
||||
+1640
-539
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user