feat: support string login in build_config and add substitute_mapping_values (#63)
* feat: support string login in build_config and add substitute_mapping_values (#61, #62) Extend build_config() to accept login: int | str | None. String logins are coerced via the existing coerce_login() helper (empty/whitespace → None, numeric strings → int, non-numeric → ValueError). When allow_whole_dollar_env=True, ${ENV} and $ENV placeholders are expanded before coercion, consistent with path/password/server behavior. Add substitute_mapping_values(), a generic recursive helper that substitutes environment placeholders in nested dicts/lists only for caller-selected mapping keys. Non-selected fields (including literal dollar signs) are preserved exactly. Supports blank_string_keys_as_none to normalise empty strings to None after substitution. No application- specific key names (e.g. mt5_login) are hard-coded in mt5cli. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Bump version to v0.9.5 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs+test: clarify substitute_mapping_values docstring and pin tuple behaviour - Adds sentence noting list-element strings are never substituted (only immediate dict values are), addressing reviewer finding #1. - Rewrites Returns section to accurately describe scalar pass-through behaviour, addressing reviewer finding #2. - Adds recursion-depth caveat to the generic-utility docstring, addressing reviewer finding #4. - Adds test_tuple_container_not_traversed to pin the existing silent tuple-exclusion contract, addressing reviewer finding #3. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs: update public contract and README for build_config login coercion and substitute_mapping_values - Expands build_config row to document login: int | str | None, numeric-string coercion, blank-string handling, and env placeholder expansion when allow_whole_dollar_env=True. - Adds substitute_mapping_values to the stable SDK table with a note that key names are never hard-coded in mt5cli. - Extends allow_whole_dollar_env paragraph to list substitute_mapping_values. - README: adds build_config env-placeholder example and imports to the trading lifecycle snippet. - README: extends credential-resolution bullet with a substitute_mapping_values usage example using generic key names. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: agent <agent@localhost> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Daichi Narushima
+13
-11
@@ -28,23 +28,25 @@ These names are exported from `mt5cli` and covered by the contract in
|
||||
|
||||
### Session lifecycle and configuration
|
||||
|
||||
| Symbol | Role |
|
||||
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
||||
| `MT5Client` | Read-only data client with optional `order_check` / `order_send` |
|
||||
| `build_config` | Build `pdmt5.Mt5Config` from connection fields |
|
||||
| `mt5_session` | Context manager: initialize, login, yield client, shutdown |
|
||||
| `create_trading_client`, `mt5_trading_session` | Trading-capable `pdmt5.Mt5TradingClient` lifecycle |
|
||||
| `AccountSpec` | Generic account group: symbols plus optional credentials |
|
||||
| `resolve_account_spec`, `resolve_account_specs` | Merge overrides and expand `${ENV_VAR}` placeholders; opt-in `allow_whole_dollar_env` for bare `$NAME` |
|
||||
| `substitute_env_placeholders` | Replace `${NAME}` substrings from the environment; opt-in `allow_whole_dollar_env` for whole-value `$NAME` |
|
||||
| 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`.
|
||||
|
||||
Pass `allow_whole_dollar_env=True` to `substitute_env_placeholders()`,
|
||||
`resolve_account_spec()`, `resolve_account_specs()`, and `build_config()` to
|
||||
additionally expand strings whose entire value is a bare `$ENV_NAME` identifier.
|
||||
`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.
|
||||
|
||||
Reference in New Issue
Block a user