mt5cli 0.9.5__tar.gz → 0.9.7__tar.gz

{mt5cli-0.9.5 → mt5cli-0.9.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mt5cli
-Version: 0.9.5
+Version: 0.9.7
 Summary: Generic MT5 data and execution infrastructure for Python applications
 Project-URL: Repository, https://github.com/dceoy/mt5cli.git
 Author-email: dceoy <dceoy@users.noreply.github.com>
@@ -18,8 +18,9 @@ Classifier: Topic :: Office/Business :: Financial :: Investment
 Requires-Python: <3.14,>=3.11
 Requires-Dist: click>=8.1.0
 Requires-Dist: pdmt5>=0.3.0
-Requires-Dist: pyarrow>=19.0.0
 Requires-Dist: typer>=0.15.0
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=19.0.0; extra == 'parquet'
 Description-Content-Type: text/markdown
 
 # mt5cli
@@ -53,6 +54,12 @@ Built on top of [pdmt5](https://github.com/dceoy/pdmt5), a pandas-based data han
 pip install -U mt5cli MetaTrader5
 ```
 
+Parquet export is not included by default. To enable it, install the `parquet` extra:
+
+```bash
+pip install -U "mt5cli[parquet]" MetaTrader5
+```
+
 ## Python API (downstream packages)
 
 Import `MT5Client` for generic MT5 data access, schema normalization, and optional order primitives.
@@ -202,10 +209,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`
 

{mt5cli-0.9.5 → mt5cli-0.9.7}/README.md

@@ -29,6 +29,12 @@ Built on top of [pdmt5](https://github.com/dceoy/pdmt5), a pandas-based data han
 pip install -U mt5cli MetaTrader5
 ```
 
+Parquet export is not included by default. To enable it, install the `parquet` extra:
+
+```bash
+pip install -U "mt5cli[parquet]" MetaTrader5
+```
+
 ## Python API (downstream packages)
 
 Import `MT5Client` for generic MT5 data access, schema normalization, and optional order primitives.
@@ -178,10 +184,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`
 

{mt5cli-0.9.5 → mt5cli-0.9.7}/docs/api/public-contract.md

@@ -111,6 +111,14 @@ strategy entries, exits, Kelly sizing, or signal logic.
 | `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.
 
@@ -182,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)
 

{mt5cli-0.9.5 → mt5cli-0.9.7}/docs/index.md

@@ -27,6 +27,12 @@ mt5cli provides a stable `MT5Client` Python API, standardized dataset schemas, s
 pip install mt5cli
 ```
 
+Parquet export is not included by default. To enable it, install the `parquet` extra:
+
+```bash
+pip install "mt5cli[parquet]"
+```
+
 ## Python API for downstream packages
 
 Import `MT5Client` for generic MT5 data access, schema normalization, and optional order primitives.

{mt5cli-0.9.5 → mt5cli-0.9.7}/mt5cli/__init__.py

@@ -120,6 +120,7 @@ from .trading import (
     OrderSide,
     OrderTimeMode,
     PositionSide,
+    ProjectionMode,
     calculate_account_projected_margin_ratio,
     calculate_margin_and_volume,
     calculate_new_position_margin_ratio,
@@ -192,6 +193,7 @@ __all__ = [
     "OrderSide",
     "OrderTimeMode",
     "PositionSide",
+    "ProjectionMode",
     "RateTarget",
     "ThrottledHistoryUpdater",
     "account_info",

{mt5cli-0.9.5 → mt5cli-0.9.7}/mt5cli/cli.py

@@ -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,

{mt5cli-0.9.5 → mt5cli-0.9.7}/mt5cli/contract.py

@@ -17,6 +17,7 @@ STABLE_SDK_EXPORTS: frozenset[str] = frozenset({
     "OrderSide",
     "OrderTimeMode",
     "PositionSide",
+    "ProjectionMode",
     "ExecutionStatus",
     "MarginVolume",
     "OrderExecutionResult",

{mt5cli-0.9.5 → mt5cli-0.9.7}/mt5cli/trading.py

@@ -25,6 +25,7 @@ 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):
@@ -127,6 +128,7 @@ __all__ = [
     "OrderSide",
     "OrderTimeMode",
     "PositionSide",
+    "ProjectionMode",
     "calculate_account_projected_margin_ratio",
     "calculate_margin_and_volume",
     "calculate_new_position_margin_ratio",
@@ -920,6 +922,16 @@ def calculate_projected_margin_ratio(
     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,
     *,
@@ -928,13 +940,22 @@ def calculate_symbol_group_margin_ratio(
     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, optional projected order margin is added for that
-    symbol. Invalid equity always raises to fail closed.
+    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
@@ -945,23 +966,22 @@ def calculate_symbol_group_margin_ratio(
             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))
-    margin = sum(
-        calculate_positions_margin_by_symbol(
-            client,
-            symbols=unique_symbols,
-            suppress_errors=suppress_errors,
-        ).values(),
-        0.0,
+    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:
-            margin += estimate_order_margin(
+            candidate_margin = estimate_order_margin(
                 client,
                 new_symbol,
                 new_position_side,
@@ -971,6 +991,10 @@ def calculate_symbol_group_margin_ratio(
             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
 
 

{mt5cli-0.9.5 → mt5cli-0.9.7}/mt5cli/utils.py

@@ -314,6 +314,7 @@ def export_dataframe(
         table_name: Table name for SQLite3 output.
 
     Raises:
+        ImportError: If the parquet format is requested but pyarrow is not installed.
         ValueError: If the output format is not supported.
     """
     if output_format == "csv":
@@ -326,6 +327,14 @@ def export_dataframe(
             indent=2,
         )
     elif output_format == "parquet":
+        try:
+            __import__("pyarrow")
+        except ImportError as exc:
+            msg = (
+                "Parquet export requires the optional dependency pyarrow. "
+                'Install it with: pip install "mt5cli[parquet]"'
+            )
+            raise ImportError(msg) from exc
         df.to_parquet(output_path, index=False)
     elif output_format == "sqlite3":
         export_dataframe_to_sqlite(

{mt5cli-0.9.5 → mt5cli-0.9.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mt5cli"
-version = "0.9.5"
+version = "0.9.7"
 description = "Generic MT5 data and execution infrastructure for Python applications"
 authors = [{name = "dceoy", email = "dceoy@users.noreply.github.com"}]
 maintainers = [{name = "dceoy", email = "dceoy@users.noreply.github.com"}]
@@ -11,7 +11,6 @@ requires-python = ">= 3.11, < 3.14"
 dependencies = [
   "pdmt5>=0.3.0",
   "click >= 8.1.0",
-  "pyarrow >= 19.0.0",
   "typer >= 0.15.0",
 ]
 classifiers = [
@@ -25,6 +24,9 @@ classifiers = [
   "Topic :: Office/Business :: Financial :: Investment",
 ]
 
+[project.optional-dependencies]
+parquet = ["pyarrow >= 19.0.0"]
+
 [project.scripts]
 mt5cli = "mt5cli.cli:main"
 
@@ -42,6 +44,7 @@ dev = [
   "pytest-mock >= 3.12.0",
   "pytest-cov >= 5.0.0",
   "pandas-stubs >= 2.2.3.250527",
+  "pyarrow >= 19.0.0",
   "mkdocs >= 1.6.1",
   "mkdocs-material >= 9.7.6",
   "mkdocstrings[python] >= 1.0.4",