From 09415975efc63d7e5b83556326ebbecbe30f12ac Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 01:49:41 +0100 Subject: [PATCH 01/28] chore: fix packaging metadata and repository hygiene Goal (v3 rewrite): turn PythonMetaTrader5 into a typed, tested library whose trading calls never block forever, with a 2.x compatibility facade. - Stop tracking the generated egg-info directory and add a .gitignore. - Declare the real license (CC-BY-NC-4.0, SPDX) instead of the contradictory MIT classifier, and ship a LICENSE file. - Mark the MetaTrader5 dependency win32-only: the official package has Windows wheels only, so an unconditional dependency breaks Linux CI and type checking. - Raise the floor to Python 3.10 (match statements, PEP 604 unions); 3.6-3.9 are end-of-life. - Configure pytest, coverage, ruff and mypy --strict. --- .gitignore | 18 +++ LICENSE | 16 +++ pyproject.toml | 122 ++++++++++++------ src/PythonMetaTrader5.egg-info/PKG-INFO | 111 ---------------- src/PythonMetaTrader5.egg-info/SOURCES.txt | 8 -- .../dependency_links.txt | 1 - src/PythonMetaTrader5.egg-info/top_level.txt | 1 - 7 files changed, 117 insertions(+), 160 deletions(-) create mode 100644 .gitignore create mode 100644 LICENSE delete mode 100644 src/PythonMetaTrader5.egg-info/PKG-INFO delete mode 100644 src/PythonMetaTrader5.egg-info/SOURCES.txt delete mode 100644 src/PythonMetaTrader5.egg-info/dependency_links.txt delete mode 100644 src/PythonMetaTrader5.egg-info/top_level.txt diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b240fa3 --- /dev/null +++ b/.gitignore @@ -0,0 +1,18 @@ +# Build artefacts +build/ +dist/ +*.egg-info/ + +# Python caches +__pycache__/ +*.py[cod] +.mypy_cache/ +.ruff_cache/ +.pytest_cache/ +.coverage +coverage.xml +htmlcov/ + +# Local environments and secrets +.venv/ +.env diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..17fc111 --- /dev/null +++ b/LICENSE @@ -0,0 +1,16 @@ +PythonMetaTrader5 +Copyright (c) Wiktor Jelen + +This work is licensed under the Creative Commons Attribution-NonCommercial 4.0 +International License (CC BY-NC 4.0). + +You are free to share and adapt this work for non-commercial purposes, provided +you give appropriate credit, link to the license, and indicate if changes were +made. + +Full legal code: https://creativecommons.org/licenses/by-nc/4.0/legalcode +Summary: https://creativecommons.org/licenses/by-nc/4.0/ + +THE WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. TRADING FINANCIAL +INSTRUMENTS CARRIES RISK; THE AUTHORS ARE NOT LIABLE FOR ANY LOSSES INCURRED +THROUGH THE USE OF THIS SOFTWARE. diff --git a/pyproject.toml b/pyproject.toml index 9c439c4..4ae66e4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,39 +1,83 @@ -[build-system] -requires = ["setuptools>=61.0", "wheel"] -build-backend = "setuptools.build_meta" - -[project] -name = "PythonMetaTrader5" -version = "2.3.2" -description = "Connect MT5 with Python" -readme = "README.md" -requires-python = ">=3.6" -license = {text = "CC BY-NC 4.0"} - -authors = [{ name = "Wiktor Jelen", email = "wiktorjn@gmail.com" }] - -classifiers = [ - "Programming Language :: Python :: 3", - "License :: OSI Approved :: MIT License", - "Operating System :: OS Independent" -] - -dependencies = [ - "MetaTrader5", - "loguru", - "pyautogui" -] - -[project.urls] -Homepage = "https://github.com/Akinzou/MetaTrader5-Python" -"Bug Tracker" = "https://github.com/Akinzou/MetaTrader5-Python/issues" - -[tool.setuptools.packages.find] -where = ["src"] - - - - - - - +[build-system] +# setuptools>=77 is the first release that accepts a PEP 639 SPDX `license` string; +# older versions would silently publish the wrong license metadata again. +requires = ["setuptools>=77", "wheel"] +build-backend = "setuptools.build_meta" + +[project] +name = "PythonMetaTrader5" +version = "3.0.0" +description = "Safe, typed trading layer over the official MetaTrader5 Python API" +readme = "README.md" +requires-python = ">=3.10" +license = "CC-BY-NC-4.0" +license-files = ["LICENSE"] +authors = [{ name = "Wiktor Jelen", email = "wiktorjn@gmail.com" }] +keywords = ["metatrader5", "mt5", "trading", "forex", "algotrading"] +classifiers = [ + "Development Status :: 5 - Production/Stable", + "Intended Audience :: Developers", + "Intended Audience :: Financial and Insurance Industry", + "Operating System :: Microsoft :: Windows", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", + "Programming Language :: Python :: 3.14", + "Topic :: Office/Business :: Financial :: Investment", + "Typing :: Typed", +] +# The official MetaTrader5 package ships Windows wheels only. The marker keeps the +# package installable on Linux/macOS (CI, type checking, unit tests against fakes) +# instead of failing the whole install. +dependencies = ["MetaTrader5; sys_platform == 'win32'"] + +[project.optional-dependencies] +dev = ["pytest>=8", "pytest-cov>=5", "ruff>=0.6", "mypy>=1.10", "build>=1.2", "twine>=5"] + +[project.urls] +Homepage = "https://github.com/Akinzou/MetaTrader5-Python" +"Bug Tracker" = "https://github.com/Akinzou/MetaTrader5-Python/issues" +Changelog = "https://github.com/Akinzou/MetaTrader5-Python/blob/master/CHANGELOG.md" + +[tool.setuptools.packages.find] +where = ["src"] + +[tool.setuptools.package-data] +PythonMetaTrader5 = ["py.typed"] + +[tool.pytest.ini_options] +testpaths = ["tests"] +addopts = "-ra --strict-markers" +markers = ["integration: needs a running MetaTrader 5 terminal and MT5_* credentials"] + +[tool.coverage.run] +source = ["PythonMetaTrader5"] +branch = true + +[tool.coverage.report] +fail_under = 95 +show_missing = true +exclude_also = ["if TYPE_CHECKING:", "raise AssertionError"] + +[tool.ruff] +line-length = 100 +target-version = "py310" + +[tool.ruff.lint] +select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF", "N", "S", "PL", "C4", "PT", "RET"] +ignore = ["PLR0913"] + +[tool.ruff.lint.per-file-ignores] +# The distribution/import name predates this rewrite; renaming it breaks every user. +"src/PythonMetaTrader5/__init__.py" = ["N999"] +# The 2.x public method names (Buy, GetPositions, ToEffect...) are the compatibility contract. +"src/PythonMetaTrader5/legacy/*.py" = ["N802", "N803", "N999"] +"tests/**/*.py" = ["S101", "PLR2004", "N999"] + +[tool.mypy] +strict = true +python_version = "3.10" +mypy_path = "src" +packages = ["PythonMetaTrader5"] diff --git a/src/PythonMetaTrader5.egg-info/PKG-INFO b/src/PythonMetaTrader5.egg-info/PKG-INFO deleted file mode 100644 index a4d9385..0000000 --- a/src/PythonMetaTrader5.egg-info/PKG-INFO +++ /dev/null @@ -1,111 +0,0 @@ -Metadata-Version: 2.1 -Name: PythonMetaTrader5 -Version: 1.0.9 -Summary: Connect MT5 with Python -Home-page: https://github.com/Akinzou/MetaTrader5-Python -Author: Wiktor Jelen -Author-email: wiktorjn@gmail.com -Project-URL: Bug Tracker, https://github.com/Akinzou/MetaTrader5-Python/issues -Classifier: Programming Language :: Python :: 3 -Classifier: License :: OSI Approved :: MIT License -Classifier: Operating System :: OS Independent -Requires-Python: >=3.6 -Description-Content-Type: text/markdown - -# Python Library for MetaTrader 5 Connection - -![MetaTrader 5] -This Python library enables you to connect with the MetaTrader 5 trading platform and interact with its features using Python. It allows executing trading operations, fetching market data, receiving notifications, and more. - -## Requirements - -To use this library, you need: - -Python 3.x -MetaTrader 5 trading platform installed -MetaTrader 5 Python API (MetaTrader5 module) -colorama - -## Installation - -To install the library, use `pip`: - -```bash -pip install MetaTrader5 -pip install PythonMetaTrader5 -``` -# Getting Started - -Import the library in your Python script: - -``` -from MetaTrader5 import * -``` - -Initialize the MetaTrader 5 library by calling the initialize() function. - -Create an instance of the Broker class by providing your MetaTrader 5 login credentials and server: - -``` -broker = Broker(log=your_mt5_login, password="your_mt5_password", server="your_mt5_server") -``` -### After successful login, you can perform trading operations such as placing orders and managing positions. - - -## Available Functions: -### Placing Orders: - -``Buy(symbol, volume, price=None, *, comment=None, ticket=None):`` Places a Buy market order or limit order if price is specified. - -``BuySL(symbol, volume, sl, price=None, *, comment=None, ticket=None):`` Places a Buy market order or limit order with a Stop Loss (SL) price if price is specified. - -``Sell(symbol, volume, price=None, *, comment=None, ticket=None):`` Places a Sell market order or limit order if price is specified. - -``SellSL(symbol, volume, sl, price=None, *, comment=None, ticket=None):`` Places a Sell market order or limit order with a Stop Loss (SL) price if price is specified. - -``BuyLimit(symbol, volume, stoplimit, price=None, comment=None, ticket=None):`` Places a Buy limit order with the specified stoplimit price. - -``SellLimit(symbol, volume, stoplimit, price=None, comment=None, ticket=None):`` Places a Sell limit order with the specified stoplimit price. - - -### Managing Positions: -``Close(symbol, *, comment=None, ticket=None):`` Closes all positions for the specified symbol or a specific position indicated by ticket. - -``CancelOrders(symbol):`` Cancels all pending orders for the specified symbol. - - -### Miscellaneous: -``Disconnect():`` Closes the connection to the MetaTrader 5 trading platform. - - -## Example Usage: -``` -from MetaTrader5 import * - -# Initialize the MetaTrader 5 library -initialize() - -# Create a broker instance and log in -broker = Broker(log=your_mt5_login, password="your_mt5_password", server="your_mt5_server") - -# Place a Buy market order for 0.1 lot of EURUSD -broker.Buy("EURUSD", 0.1) - -# Place a limit order for gold (if price is lower than 1900 it will be execute immediately -broker.BuyLimit("XAUUSD", 0.01, 1900) - -# Close all positions for EURUSD -broker.Close("EURUSD") - -# Cancel all pending orders for EURUSD -broker.CancelOrders("EURUSD") - -# Disconnect from the MetaTrader 5 platform -broker.Disconnect() -``` - - -## Note: -It is important to have the MetaTrader 5 trading platform running and logged in with the provided credentials before using this library. -This library is provided "as is" without any warranty. Use it at your own risk. -Before using this library in a live trading environment, thoroughly test it on a demo account to ensure its correctness and reliability. diff --git a/src/PythonMetaTrader5.egg-info/SOURCES.txt b/src/PythonMetaTrader5.egg-info/SOURCES.txt deleted file mode 100644 index bc1a45d..0000000 --- a/src/PythonMetaTrader5.egg-info/SOURCES.txt +++ /dev/null @@ -1,8 +0,0 @@ -README.md -pyproject.toml -setup.cfg -src/PythonMetaTrader5/__init__.py -src/PythonMetaTrader5.egg-info/PKG-INFO -src/PythonMetaTrader5.egg-info/SOURCES.txt -src/PythonMetaTrader5.egg-info/dependency_links.txt -src/PythonMetaTrader5.egg-info/top_level.txt \ No newline at end of file diff --git a/src/PythonMetaTrader5.egg-info/dependency_links.txt b/src/PythonMetaTrader5.egg-info/dependency_links.txt deleted file mode 100644 index 8b13789..0000000 --- a/src/PythonMetaTrader5.egg-info/dependency_links.txt +++ /dev/null @@ -1 +0,0 @@ - diff --git a/src/PythonMetaTrader5.egg-info/top_level.txt b/src/PythonMetaTrader5.egg-info/top_level.txt deleted file mode 100644 index 5c542ee..0000000 --- a/src/PythonMetaTrader5.egg-info/top_level.txt +++ /dev/null @@ -1 +0,0 @@ -PythonMetaTrader5 From 843218ab1c760c4f4402460e5e39b929a7dbee95 Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 01:51:58 +0100 Subject: [PATCH 02/28] feat(domain): add pure trading rules with a Result type Replaces the 2.x single-file Broker (its behaviour returns as a compatibility facade in a later commit). The domain has no I/O and never imports MetaTrader5. - Result (Ok/Err) for every expected failure at boundaries. - SymbolSpec: price normalisation on the tick grid, not only to `digits` (index CFDs with tick 0.25 were rejected by 2.x), volume min/max/step validation, filling-mode choice from the symbol's flags. - Stop: SL/TP as a price or as a distance in points (2.x semantics kept). - Retcode classification. Retry only codes where the server provably did not execute; TIMEOUT/CONNECTION are not retried because the order may already be live and a retry would open a duplicate position. - Comments over 31 characters are rejected instead of silently truncated. --- pyproject.toml | 10 +- src/PythonMetaTrader5/__init__.py | 535 ----------------------- src/PythonMetaTrader5/domain/__init__.py | 1 + src/PythonMetaTrader5/domain/errors.py | 44 ++ src/PythonMetaTrader5/domain/market.py | 80 ++++ src/PythonMetaTrader5/domain/orders.py | 51 +++ src/PythonMetaTrader5/domain/retcodes.py | 74 ++++ src/PythonMetaTrader5/domain/stops.py | 41 ++ src/PythonMetaTrader5/domain/symbol.py | 72 +++ src/PythonMetaTrader5/py.typed | 0 src/PythonMetaTrader5/result.py | 41 ++ tests/unit/test_market.py | 29 ++ tests/unit/test_orders.py | 36 ++ tests/unit/test_result.py | 21 + tests/unit/test_retcodes.py | 45 ++ tests/unit/test_stops.py | 37 ++ tests/unit/test_symbol.py | 60 +++ 17 files changed, 637 insertions(+), 540 deletions(-) create mode 100644 src/PythonMetaTrader5/domain/__init__.py create mode 100644 src/PythonMetaTrader5/domain/errors.py create mode 100644 src/PythonMetaTrader5/domain/market.py create mode 100644 src/PythonMetaTrader5/domain/orders.py create mode 100644 src/PythonMetaTrader5/domain/retcodes.py create mode 100644 src/PythonMetaTrader5/domain/stops.py create mode 100644 src/PythonMetaTrader5/domain/symbol.py create mode 100644 src/PythonMetaTrader5/py.typed create mode 100644 src/PythonMetaTrader5/result.py create mode 100644 tests/unit/test_market.py create mode 100644 tests/unit/test_orders.py create mode 100644 tests/unit/test_result.py create mode 100644 tests/unit/test_retcodes.py create mode 100644 tests/unit/test_stops.py create mode 100644 tests/unit/test_symbol.py diff --git a/pyproject.toml b/pyproject.toml index 4ae66e4..f5ee621 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -67,14 +67,14 @@ target-version = "py310" [tool.ruff.lint] select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF", "N", "S", "PL", "C4", "PT", "RET"] -ignore = ["PLR0913"] +# N999: the import name `PythonMetaTrader5` predates this rewrite; renaming it to +# snake_case would break every existing `from PythonMetaTrader5 import Broker`. +ignore = ["PLR0913", "N999"] [tool.ruff.lint.per-file-ignores] -# The distribution/import name predates this rewrite; renaming it breaks every user. -"src/PythonMetaTrader5/__init__.py" = ["N999"] # The 2.x public method names (Buy, GetPositions, ToEffect...) are the compatibility contract. -"src/PythonMetaTrader5/legacy/*.py" = ["N802", "N803", "N999"] -"tests/**/*.py" = ["S101", "PLR2004", "N999"] +"src/PythonMetaTrader5/legacy/*.py" = ["N802", "N803", "N815"] +"tests/**/*.py" = ["S101", "PLR2004"] [tool.mypy] strict = true diff --git a/src/PythonMetaTrader5/__init__.py b/src/PythonMetaTrader5/__init__.py index 777557f..e69de29 100644 --- a/src/PythonMetaTrader5/__init__.py +++ b/src/PythonMetaTrader5/__init__.py @@ -1,535 +0,0 @@ -import time -from MetaTrader5 import * -from loguru import logger -import pyautogui - - -class Broker: - RetCodes = { - 10027: "Enable Algo Trading in MetaTrader5 app", - 10018: "Market closed", - 10016: "Wrong SL", - } - - log = None - password = None - server = None - - def __init__(self, log, password, server): - self.log = log - self.password = str(password) - self.server = str(server) - - initialize() - if login(self.log, self.password, server=self.server): - logger.success("Login succes") - acc_info = account_info() - logger.info(str(acc_info)) - else: - logger.error(f"Login failed: {self.log}") - - def login(self, ToEffect=False): - while True: - logger.info(f"Login on: {self.log}") - if login(self.log, self.password, server=self.server): - logger.success("OK") - time.sleep(0.5) - return True - if ToEffect is False: - logger.error("ERROR") - return False - - # -------------------- Symbol meta & normalization -------------------- - - def _symbol_meta(self, symbol): - """ - Returns (point, digits). - point -> minimal price step (MT5) - digits -> number of decimal places - """ - info = symbol_info(symbol) - if info is None: - logger.error(f"{self.log}: symbol_info({symbol}) returned None") - return None, None - point = float(info.point) - digits = int(info.digits) - return point, digits - - def _normalize(self, price, digits): - if price is None: - return None - step = 10 ** (-digits) - return round(float(price) / step) * step - - # -------------------- Low-level senders -------------------- - - def _RawOrderClose(self, order_type, symbol, volume, price, comment=None, ticket=None): - order = { - "action": TRADE_ACTION_DEAL, - "symbol": symbol, - "volume": float(volume), - "type": order_type, - "price": float(price), - "deviation": 10, - "type_filling": ORDER_FILLING_IOC, - } - if comment is not None: - order["comment"] = comment - if ticket is not None: - order["position"] = ticket - return order_send(order) - - def _RawOrder(self, order_type, symbol, volume, price, sl=None, tp=None, comment=None, ticket=None): - volume = float(volume) - - # normalize prices to instrument digits before sending - info = symbol_info(symbol) - if info: - digits = int(info.digits) - price = self._normalize(price, digits) - sl = self._normalize(sl, digits) if sl is not None else None - tp = self._normalize(tp, digits) if tp is not None else None - - order = { - "action": TRADE_ACTION_DEAL, - "symbol": symbol, - "volume": volume, - "type": order_type, - "price": price, - "deviation": 10, - "type_filling": ORDER_FILLING_FOK, - } - if comment is not None: - order["comment"] = comment - if ticket is not None: - order["position"] = ticket - if sl is not None: - order["sl"] = float(sl) - if tp is not None: - order["tp"] = float(tp) - return order_send(order) - - def _RawOrderLimit(self, order_type, symbol, volume, price, limit, comment=None, ticket=None): - # MT5 uses 'price' for the pending level; keep signature consistent - info = symbol_info(symbol) - digits = int(info.digits) if info else 5 - limit = self._normalize(limit, digits) - - order = { - "action": TRADE_ACTION_PENDING, - "symbol": symbol, - "volume": float(volume), - "type": order_type, - "price": float(limit), - "deviation": 10, - "type_filling": ORDER_FILLING_IOC, - } - if comment is not None: - order["comment"] = comment - if ticket is not None: - order["position"] = ticket - return order_send(order) - - # -------------------- Positions I/O -------------------- - - def _pos_to_dict(self, p): - """Serialize MT5 position to a dict (for as_dict=True).""" - if p is None: - return None - return { - "ticket": p.ticket, - "symbol": p.symbol, - "type": p.type, # ORDER_TYPE_BUY / ORDER_TYPE_SELL - "volume": float(p.volume), - "price_open": float(p.price_open), - "sl": float(p.sl) if p.sl else None, - "tp": float(p.tp) if p.tp else None, - "price_current": float(p.price_current), - "profit": float(p.profit), - "time": int(p.time), # epoch - "magic": int(p.magic), - "comment": p.comment, - } - - # -------------------- Positions by symbol -------------------- - - def GetPositionsBySymbol(self, symbol: str, as_dict: bool = False): - """ - Return all open positions for the given symbol. - If as_dict=True -> list of dictionaries. - """ - try: - positions = positions_get(symbol=symbol) - except Exception as e: - logger.error(f"{self.log}: GetPositionsBySymbol exception: {e}") - return [] - - positions = list(positions) if positions else [] - if as_dict: - return [self._pos_to_dict(p) for p in positions] - return positions - - def GetPositions(self, symbol=None, *, ticket=None, as_dict: bool = False): - """ - Return positions with the same filtering semantics as Close(): - - if ticket is provided -> only that position - - elif symbol is provided -> all positions for that symbol - - else -> all open positions - """ - try: - if ticket is not None: - pos = positions_get(ticket=ticket) - elif symbol is not None: - pos = positions_get(symbol=symbol) - else: - pos = positions_get() - except Exception as e: - logger.error(f"{self.log}: GetPositions exception: {e}") - return [] - - pos = list(pos) if pos else [] - if as_dict: - return [self._pos_to_dict(p) for p in pos] - return pos - - def GetPosition(self, symbol=None, *, ticket=None, as_dict: bool = False): - """ - Return the first matching position or None. - Convenient when you expect at most one. - """ - pos_list = self.GetPositions(symbol=symbol, ticket=ticket, as_dict=False) - if not pos_list: - return None if not as_dict else None - return self._pos_to_dict(pos_list[0]) if as_dict else pos_list[0] - - # -------------------- SL/TP computation: absolute or offset IN POINTS -------------------- - - def _compute_sl_tp(self, order_type, symbol, sl, tp, sl_type: str, tp_type: str): - """ - Return (sl_val, tp_val) as absolute prices. - - 'absolute' -> values are prices (e.g., 1.12345), only normalized - - 'offset' -> values are POINTS away from the current price: - BUY : SL = ask - |sl|*point, TP = ask + |tp|*point - SELL: SL = bid + |sl|*point, TP = bid - |tp|*point - """ - sl_val = float(sl) if sl is not None else None - tp_val = float(tp) if tp is not None else None - sl_type = (sl_type or "absolute").lower() - tp_type = (tp_type or "absolute").lower() - - info_tick = symbol_info_tick(symbol) - if info_tick is None: - logger.error(f"{self.log}: symbol_info_tick({symbol}) returned None (SL/TP compute)") - return None, None - - point, digits = self._symbol_meta(symbol) - if point is None: - return None, None - - is_buy = (order_type == ORDER_TYPE_BUY) - ref_price = info_tick.ask if is_buy else info_tick.bid - - if sl_val is not None: - if sl_type == "absolute": - pass - elif sl_type == "offset": - sl_val = ref_price - abs(sl_val) * point if is_buy else ref_price + abs(sl_val) * point - else: - logger.error(f"{self.log}: invalid sl_type '{sl_type}' (use 'absolute'|'offset')") - return None, None - - if tp_val is not None: - if tp_type == "absolute": - pass - elif tp_type == "offset": - tp_val = ref_price + abs(tp_val) * point if is_buy else ref_price - abs(tp_val) * point - else: - logger.error(f"{self.log}: invalid tp_type '{tp_type}' (use 'absolute'|'offset')") - return None, None - - sl_val = self._normalize(sl_val, digits) if sl_val is not None else None - tp_val = self._normalize(tp_val, digits) if tp_val is not None else None - return sl_val, tp_val - - # -------------------- Single market-entry function -------------------- - - def OpenPosition( - self, - symbol, - side, - volume, - *, - sl=None, - tp=None, - price=None, - comment=None, - ticket=None, - sl_type: str = "absolute", # 'absolute' (price) or 'offset' (POINTS) - tp_type: str = "absolute", # 'absolute' (price) or 'offset' (POINTS) - ): - """ - Open a market position. - side: "buy"/"sell" (also accepts "long"/"short") - SL/TP: - - sl_type/tp_type == 'absolute': pass absolute prices - - sl_type/tp_type == 'offset' : pass POINTS from current price - price: if None -> use current ask/bid and retry on known transient errors - """ - side = str(side).lower() - if side not in ("buy", "sell", "long", "short"): - logger.error(f"{self.log}: invalid side '{side}' (use 'buy'/'sell')") - return None - - order_type = ORDER_TYPE_BUY if side in ("buy", "long") else ORDER_TYPE_SELL - - sl_val, tp_val = self._compute_sl_tp(order_type, symbol, sl, tp, sl_type, tp_type) - - # direct-price mode - if price is not None: - return self._RawOrder(order_type, symbol, volume, price, sl_val, tp_val, comment, ticket) - - # current-tick mode with retries - while True: - info = symbol_info_tick(symbol) - if info is None: - logger.error(f"{self.log}: symbol_info_tick({symbol}) returned None") - return None - - curr_price = info.ask if order_type == ORDER_TYPE_BUY else info.bid - r = self._RawOrder(order_type, symbol, volume, curr_price, sl_val, tp_val, comment, ticket) - - if r is None: - logger.error(f"{self.log}: order_send returned None") - return None - - if r.retcode == TRADE_RETCODE_DONE or r.retcode == 10009: - action = "long" if order_type == ORDER_TYPE_BUY else "short" - details = [] - if sl_val is not None: - details.append(f"SL {sl_val}") - if tp_val is not None: - details.append(f"TP {tp_val}") - suffix = f" ({', '.join(details)})" if details else "" - logger.success(f"{self.log}: {action} {symbol}{suffix}") - return r - - if r.retcode in self.RetCodes: - action = "long" if order_type == ORDER_TYPE_BUY else "short" - logger.error(f"ERROR CAN NOT OPEN {self.log}: {action} {symbol}") - logger.error(self.RetCodes[r.retcode]) - if r.retcode == 10027: - logger.info(f"Enabling algotrading {self.log} {symbol}") - time.sleep(1) - pyautogui.hotkey("ctrl", "e") - if r.retcode == 10016: - return r - time.sleep(0.5) - else: - action = "long" if order_type == ORDER_TYPE_BUY else "short" - logger.error(f"ERROR CAN NOT OPEN TRYING AGAIN {self.log}: {action} {symbol}") - logger.info(f"RetCode: {r.retcode}") - logger.info(f"Comment: {r.comment}") - time.sleep(0.5) - - # -------------------- Backward-compat wrappers -------------------- - - def Buy(self, symbol, volume, price=None, *, comment=None, ticket=None): - return self.OpenPosition(symbol, "buy", volume, price=price, comment=comment, ticket=ticket) - - def BuySL(self, symbol, volume, sl, price=None, *, comment=None, ticket=None, sl_type: str = "absolute"): - return self.OpenPosition( - symbol, "buy", volume, sl=sl, price=price, comment=comment, ticket=ticket, sl_type=sl_type - ) - - def Sell(self, symbol, volume, price=None, *, comment=None, ticket=None): - return self.OpenPosition(symbol, "sell", volume, price=price, comment=comment, ticket=ticket) - - def SellSL(self, symbol, volume, sl, price=None, *, comment=None, ticket=None, sl_type: str = "absolute"): - return self.OpenPosition( - symbol, "sell", volume, sl=sl, price=price, comment=comment, ticket=ticket, sl_type=sl_type - ) - - # -------------------- Closing logic -------------------- - - def Close(self, symbol, *, comment=None, ticket=None): - close = False - if ticket is not None: - positions = positions_get(ticket=ticket) - else: - positions = positions_get(symbol=symbol) - - lenpositions = len(positions) - if positions: - while True: - for pos in positions: - if pos.type == ORDER_TYPE_BUY or pos.type == ORDER_TYPE_SELL: - for _ in range(10): - info = symbol_info_tick(symbol) - if info is None: - return None - if pos.type == ORDER_TYPE_BUY: - r = self._RawOrderClose( - ORDER_TYPE_SELL, symbol, pos.volume, info.bid, comment, pos.ticket - ) - close = True - else: - r = self._RawOrderClose( - ORDER_TYPE_BUY, symbol, pos.volume, info.ask, comment, pos.ticket - ) - close = True - if r is None: - return None - if r.retcode != TRADE_RETCODE_REQUOTE and r.retcode != TRADE_RETCODE_PRICE_OFF: - if r.retcode == TRADE_RETCODE_DONE: - logger.info(f"{self.log}: closing all {symbol}") - lenpositions -= 1 - break - if r.retcode in self.RetCodes: - logger.error(f"ERROR CAN NOT CLOSE {self.log} {symbol}") - logger.error(self.RetCodes[r.retcode]) - time.sleep(0.5) - if not lenpositions: - break - if r.retcode == 10027: - logger.info(f"Enabling algotrading {self.log} {symbol}") - time.sleep(1) - pyautogui.hotkey("ctrl", "e") - - if not close: - logger.info(f"{self.log}: there is no orders to close") - return False - - # -------------------- Pending orders -------------------- - - def SellLimit(self, symbol, volume, stoplimit, price=None, comment=None, ticket=None): - OpenedInstantly = False - if price is not None: - logger.error("Price have to be none") - return - - while True: - info = symbol_info_tick(symbol) - if float(info.bid) >= float(stoplimit): - r = self._RawOrder(ORDER_TYPE_SELL, symbol, float(volume), info.bid, comment=comment, ticket=ticket) - OpenedInstantly = True - else: - r = self._RawOrderLimit( - ORDER_TYPE_SELL_LIMIT, symbol, float(volume), info.bid, float(stoplimit), comment, ticket - ) - OpenedInstantly = False - - if r.retcode == 10009: - if OpenedInstantly: - logger.success(f"{self.log}: opened short on: {symbol} beacues of ask is > or = limit price") - else: - logger.success(f"{self.log}: opened short limit on: {symbol} price: {stoplimit}") - break - else: - if r.retcode in self.RetCodes: - logger.error(f"ERROR CAN NOT OPEN {self.log} sell limit on: {symbol} price: {stoplimit}") - logger.error(self.RetCodes[r.retcode]) - if r.retcode == 10027: - logger.info(f"Enabling algotrading {self.log} {symbol}") - time.sleep(1) - pyautogui.hotkey("ctrl", "e") - time.sleep(0.5) - else: - logger.error( - f"ERROR CAN NOT OPEN TRYING AGAIN {self.log} sell limit on: {symbol} price: {stoplimit}" - ) - logger.info(f"RetCode: {r.retcode}") - logger.info(f"Comment: {r.comment}") - time.sleep(0.5) - return r - - def BuyLimit(self, symbol, volume, stoplimit, price=None, comment=None, ticket=None): - OpenedInstantly = False - if price is not None: - logger.error("Price have to be none") - return - - while True: - info = symbol_info_tick(symbol) - if float(info.ask) <= float(stoplimit): - r = self._RawOrder(ORDER_TYPE_BUY, symbol, float(volume), info.ask, comment=comment, ticket=ticket) - OpenedInstantly = True - else: - r = self._RawOrderLimit( - ORDER_TYPE_BUY_LIMIT, symbol, float(volume), info.ask, float(stoplimit), comment, ticket - ) - OpenedInstantly = False - - if r.retcode == 10009: - if OpenedInstantly: - logger.success(f"{self.log}: opened long on: {symbol} beacues of ask is < or = limit price") - else: - logger.success(f"{self.log}: opened long limit on: {symbol} price: {stoplimit}") - break - else: - if r.retcode in self.RetCodes: - logger.error(f"ERROR CAN NOT OPEN {self.log} long limit on: {symbol} price: {stoplimit}") - logger.error(self.RetCodes[r.retcode]) - if r.retcode == 10027: - logger.info(f"Enabling algotrading {self.log} {symbol}") - time.sleep(1) - pyautogui.hotkey("ctrl", "e") - time.sleep(0.5) - else: - logger.error( - f"ERROR CAN NOT OPEN TRYING AGAIN {self.log} long limit on: {symbol} price: {stoplimit}" - ) - logger.info(f"RetCode: {r.retcode}") - logger.info(f"Comment: {r.comment}") - time.sleep(0.5) - return r - - # -------------------- Cancel pending orders -------------------- - - def _RawCancelOrder(self, order_number): - request = { - "action": TRADE_ACTION_REMOVE, - "order": order_number, - "comment": "Order Removed", - } - return order_send(request) - - def CancelOrders(self, symbol): - orders = orders_get() - limit_orders = [ - order - for order in orders - if order.type == ORDER_TYPE_BUY_LIMIT or order.type == ORDER_TYPE_SELL_LIMIT - ] - lenpositions = len(limit_orders) - - while True: - r = None - for order in limit_orders: - if order.symbol == symbol: - r = self._RawCancelOrder(order.ticket) - - if r.retcode != TRADE_RETCODE_REQUOTE and r.retcode != TRADE_RETCODE_PRICE_OFF: - if r.retcode == TRADE_RETCODE_DONE: - logger.info(f"{self.log}: order have been just cancelled on: {symbol}") - lenpositions -= 1 - break - if r.retcode in self.RetCodes: - logger.error(f"ERROR CAN NOT CLOSE {self.log} {symbol}") - logger.error(self.RetCodes[r.retcode]) - time.sleep(0.5) - - if not lenpositions: - break - if r is not None and r.retcode == 10027: - logger.info(f"Enabling algotrading {self.log} {symbol}") - time.sleep(1) - pyautogui.hotkey("ctrl", "e") - - if not len(limit_orders): - logger.info(f"{self.log}: there is no orders to cancel") - - # -------------------- Disconnect -------------------- - - def Disconnect(self): - shutdown() - logger.info("Disconnected from MT5") diff --git a/src/PythonMetaTrader5/domain/__init__.py b/src/PythonMetaTrader5/domain/__init__.py new file mode 100644 index 0000000..532eb87 --- /dev/null +++ b/src/PythonMetaTrader5/domain/__init__.py @@ -0,0 +1 @@ +"""Pure trading rules: no I/O, no MetaTrader5 import.""" diff --git a/src/PythonMetaTrader5/domain/errors.py b/src/PythonMetaTrader5/domain/errors.py new file mode 100644 index 0000000..6147f62 --- /dev/null +++ b/src/PythonMetaTrader5/domain/errors.py @@ -0,0 +1,44 @@ +"""Typed failure vocabulary shared by every layer.""" + +from __future__ import annotations + +from dataclasses import dataclass +from enum import Enum +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from PythonMetaTrader5.domain.market import TradeReceipt + + +class ErrorKind(Enum): + INVALID_ARGUMENT = "invalid_argument" + INVALID_VOLUME = "invalid_volume" + INVALID_PRICE = "invalid_price" + INVALID_STOPS = "invalid_stops" + INVALID_FILLING = "invalid_filling" + NO_MONEY = "no_money" + MARKET_CLOSED = "market_closed" + TRADE_DISABLED = "trade_disabled" + ALGO_TRADING_DISABLED = "algo_trading_disabled" + LIMIT_REACHED = "limit_reached" + # The request may or may not have reached the trade server: never auto-retried. + OUTCOME_UNKNOWN = "outcome_unknown" + RETRIES_EXHAUSTED = "retries_exhausted" + REJECTED = "rejected" + SYMBOL_NOT_FOUND = "symbol_not_found" + NO_PRICE = "no_price" + TERMINAL_ERROR = "terminal_error" + CONNECTION_FAILED = "connection_failed" + + +@dataclass(frozen=True, slots=True) +class TradeError: + kind: ErrorKind + message: str + retcode: int | None = None + # Kept so callers (and the 2.x facade) can inspect the broker's raw answer. + receipt: TradeReceipt | None = None + + def __str__(self) -> str: + code = f" (retcode {self.retcode})" if self.retcode is not None else "" + return f"{self.kind.value}: {self.message}{code}" diff --git a/src/PythonMetaTrader5/domain/market.py b/src/PythonMetaTrader5/domain/market.py new file mode 100644 index 0000000..6ba56db --- /dev/null +++ b/src/PythonMetaTrader5/domain/market.py @@ -0,0 +1,80 @@ +"""Read models returned by the terminal: quotes, positions, orders, receipts.""" + +from __future__ import annotations + +from dataclasses import asdict, dataclass +from enum import Enum +from typing import Any + +from PythonMetaTrader5.domain.orders import Side + + +@dataclass(frozen=True, slots=True) +class Tick: + bid: float + ask: float + + def entry_price(self, side: Side) -> float: + return self.ask if side is Side.BUY else self.bid + + def exit_price(self, side: Side) -> float: + # Closing a long sells at bid, closing a short buys at ask. + return self.entry_price(side.opposite) + + +@dataclass(frozen=True, slots=True) +class Position: + ticket: int + symbol: str + side: Side + volume: float + price_open: float + sl: float | None + tp: float | None + price_current: float + profit: float + time: int + magic: int + comment: str + + def to_dict(self) -> dict[str, Any]: + data = asdict(self) + data["side"] = self.side.value + return data + + +class PendingKind(Enum): + LIMIT = "limit" + STOP = "stop" + STOP_LIMIT = "stop_limit" + + +@dataclass(frozen=True, slots=True) +class PendingOrder: + ticket: int + symbol: str + side: Side + kind: PendingKind + volume: float + price: float + magic: int + comment: str + + +@dataclass(frozen=True, slots=True) +class TradeReceipt: + """Broker answer to a trade request. + + Field names mirror MetaTrader5's ``OrderSendResult`` on purpose, so 2.x code + reading ``result.retcode`` / ``result.comment`` keeps working unchanged. + """ + + retcode: int + deal: int + order: int + volume: float + price: float + bid: float + ask: float + comment: str + request_id: int diff --git a/src/PythonMetaTrader5/domain/orders.py b/src/PythonMetaTrader5/domain/orders.py new file mode 100644 index 0000000..338dd2d --- /dev/null +++ b/src/PythonMetaTrader5/domain/orders.py @@ -0,0 +1,51 @@ +"""Trade direction and the order requests sent through the terminal port.""" + +from __future__ import annotations + +from enum import Enum + +from PythonMetaTrader5.domain.errors import ErrorKind, TradeError +from PythonMetaTrader5.result import Err, Ok, Result + +_SIDE_ALIASES = {"buy": "BUY", "long": "BUY", "sell": "SELL", "short": "SELL"} + + +class Side(Enum): + BUY = "buy" + SELL = "sell" + + @property + def opposite(self) -> Side: + return Side.SELL if self is Side.BUY else Side.BUY + + @property + def sign(self) -> int: + return 1 if self is Side.BUY else -1 + + @classmethod + def parse(cls, value: Side | str) -> Result[Side, TradeError]: + if isinstance(value, Side): + return Ok(value) + name = _SIDE_ALIASES.get(str(value).strip().lower()) + if name is None: + return Err( + TradeError(ErrorKind.INVALID_ARGUMENT, f"unknown side {value!r}; use buy/sell") + ) + return Ok(cls[name]) + + +# The terminal stores at most 31 characters and answers longer comments with an +# "Invalid comment argument" error instead of trimming them. +MAX_COMMENT_LENGTH = 31 + + +def validate_comment(comment: str | None) -> Result[str, TradeError]: + text = comment or "" + if len(text) > MAX_COMMENT_LENGTH: + return Err( + TradeError( + ErrorKind.INVALID_ARGUMENT, + f"comment is {len(text)} characters; the terminal accepts {MAX_COMMENT_LENGTH}", + ) + ) + return Ok(text) diff --git a/src/PythonMetaTrader5/domain/retcodes.py b/src/PythonMetaTrader5/domain/retcodes.py new file mode 100644 index 0000000..c811b74 --- /dev/null +++ b/src/PythonMetaTrader5/domain/retcodes.py @@ -0,0 +1,74 @@ +"""What a MetaTrader 5 trade-server return code means for the caller. + +Codes are integers from the MQL5 "Trade Server Return Codes" table; they are +duplicated here so the domain never imports the MetaTrader5 package. +""" + +from __future__ import annotations + +from enum import Enum + +from PythonMetaTrader5.domain.errors import ErrorKind, TradeError + + +class Outcome(Enum): + SUCCESS = "success" + RETRY = "retry" + FAIL = "fail" + + +# PLACED is how the server confirms a pending order; 2.x only accepted DONE and +# therefore re-sent limit orders that had already been placed. +_SUCCESS = frozenset({10008, 10009, 10010}) + +# Only codes where the server provably did NOT execute the request. TIMEOUT and +# CONNECTION are deliberately absent: the order may already be live, and an +# automatic retry would open a second position. +_RETRY = frozenset({10004, 10020, 10021, 10024}) + +_FAILURES: dict[int, tuple[ErrorKind, str]] = { + 10006: (ErrorKind.REJECTED, "request rejected by the server"), + 10007: (ErrorKind.REJECTED, "request cancelled by the trader"), + 10011: (ErrorKind.REJECTED, "request processing error"), + 10012: (ErrorKind.OUTCOME_UNKNOWN, "request timed out; check positions before retrying"), + 10013: (ErrorKind.INVALID_ARGUMENT, "invalid request"), + 10014: (ErrorKind.INVALID_VOLUME, "invalid volume"), + 10015: (ErrorKind.INVALID_PRICE, "invalid price"), + 10016: (ErrorKind.INVALID_STOPS, "invalid stops; check symbol stops_level"), + 10017: (ErrorKind.TRADE_DISABLED, "trading is disabled"), + 10018: (ErrorKind.MARKET_CLOSED, "market is closed"), + 10019: (ErrorKind.NO_MONEY, "not enough money"), + 10022: (ErrorKind.INVALID_ARGUMENT, "invalid order expiration"), + 10026: (ErrorKind.ALGO_TRADING_DISABLED, "autotrading disabled by the server"), + 10027: (ErrorKind.ALGO_TRADING_DISABLED, "enable Algo Trading in the MetaTrader 5 terminal"), + 10028: (ErrorKind.REJECTED, "request locked for processing"), + 10029: (ErrorKind.REJECTED, "order or position frozen"), + 10030: (ErrorKind.INVALID_FILLING, "filling mode not supported by the symbol"), + 10031: (ErrorKind.OUTCOME_UNKNOWN, "no connection to the trade server; check positions"), + 10032: (ErrorKind.TRADE_DISABLED, "operation allowed only on live accounts"), + 10033: (ErrorKind.LIMIT_REACHED, "pending orders limit reached"), + 10034: (ErrorKind.LIMIT_REACHED, "volume limit for the symbol reached"), + 10035: (ErrorKind.INVALID_ARGUMENT, "invalid or prohibited order type"), + 10036: (ErrorKind.REJECTED, "position already closed"), + 10038: (ErrorKind.INVALID_VOLUME, "close volume exceeds position volume"), + 10039: (ErrorKind.REJECTED, "a close order for this position already exists"), + 10040: (ErrorKind.LIMIT_REACHED, "open positions limit reached"), + 10041: (ErrorKind.REJECTED, "pending order activation rejected"), + 10042: (ErrorKind.TRADE_DISABLED, "only long positions are allowed"), + 10043: (ErrorKind.TRADE_DISABLED, "only short positions are allowed"), + 10044: (ErrorKind.TRADE_DISABLED, "only position closing is allowed"), + 10045: (ErrorKind.REJECTED, "FIFO rule: close older positions first"), +} + + +def classify(retcode: int) -> Outcome: + if retcode in _SUCCESS: + return Outcome.SUCCESS + if retcode in _RETRY: + return Outcome.RETRY + return Outcome.FAIL + + +def error_for(retcode: int) -> TradeError: + kind, message = _FAILURES.get(retcode, (ErrorKind.REJECTED, "unrecognised server retcode")) + return TradeError(kind, message, retcode=retcode) diff --git a/src/PythonMetaTrader5/domain/stops.py b/src/PythonMetaTrader5/domain/stops.py new file mode 100644 index 0000000..cd7bd2c --- /dev/null +++ b/src/PythonMetaTrader5/domain/stops.py @@ -0,0 +1,41 @@ +"""Stop-loss / take-profit given either as a price or as a distance in points.""" + +from __future__ import annotations + +from dataclasses import dataclass +from enum import Enum + +from PythonMetaTrader5.domain.orders import Side +from PythonMetaTrader5.domain.symbol import SymbolSpec + + +class StopKind(Enum): + PRICE = "price" + POINTS = "points" + + +@dataclass(frozen=True, slots=True) +class Stop: + value: float + kind: StopKind + + @classmethod + def at_price(cls, price: float) -> Stop: + return cls(float(price), StopKind.PRICE) + + @classmethod + def points(cls, distance: float) -> Stop: + # The sign is ignored on purpose: direction comes from the trade side, so + # `-1000` and `1000` both mean "1000 points on the losing side". + return cls(abs(float(distance)), StopKind.POINTS) + + def stop_loss(self, side: Side, reference: float, spec: SymbolSpec) -> float: + return self._resolve(-side.sign, reference, spec) + + def take_profit(self, side: Side, reference: float, spec: SymbolSpec) -> float: + return self._resolve(side.sign, reference, spec) + + def _resolve(self, direction: int, reference: float, spec: SymbolSpec) -> float: + if self.kind is StopKind.PRICE: + return spec.normalize_price(self.value) + return spec.normalize_price(reference + direction * self.value * spec.point) diff --git a/src/PythonMetaTrader5/domain/symbol.py b/src/PythonMetaTrader5/domain/symbol.py new file mode 100644 index 0000000..f38e353 --- /dev/null +++ b/src/PythonMetaTrader5/domain/symbol.py @@ -0,0 +1,72 @@ +"""Instrument specification and the rules that depend only on it.""" + +from __future__ import annotations + +from dataclasses import dataclass +from enum import Enum + +from PythonMetaTrader5.domain.errors import ErrorKind, TradeError +from PythonMetaTrader5.result import Err, Ok, Result + +# Bit flags of SYMBOL_FILLING_MODE as documented in MQL5. The Python package does +# not export them, so they are defined here rather than guessed at call sites. +_FILLING_FOK_FLAG = 1 +_FILLING_IOC_FLAG = 2 + +# Tolerances for float checks: volumes are entered as decimal literals (0.07) +# that are not exactly representable in binary floating point, so an exact +# comparison would reject valid lots. +_EPSILON = 1e-9 +_STEP_TOLERANCE = 1e-6 +# Volume precision sent to the server; well below any broker's volume_step. +_VOLUME_DECIMALS = 8 + + +class Filling(Enum): + FOK = "fok" + IOC = "ioc" + RETURN = "return" + + +@dataclass(frozen=True, slots=True) +class SymbolSpec: + name: str + digits: int + point: float + tick_size: float + volume_min: float + volume_max: float + volume_step: float + filling_flags: int + stops_level: int = 0 + + def normalize_price(self, price: float) -> float: + # A price must sit on the tick grid, not merely have `digits` decimals: + # index CFDs often have tick 0.25 with 2 digits and reject 5780.13. + step = self.tick_size if self.tick_size > 0 else self.point + return round(round(price / step) * step, self.digits) + + def validate_volume(self, volume: float) -> Result[float, TradeError]: + if volume < self.volume_min - _EPSILON or volume > self.volume_max + _EPSILON: + return Err(self._volume_error(volume, "outside")) + steps = (volume - self.volume_min) / self.volume_step + if abs(steps - round(steps)) > _STEP_TOLERANCE: + return Err(self._volume_error(volume, "not a multiple of the step within")) + snapped = self.volume_min + round(steps) * self.volume_step + return Ok(round(snapped, _VOLUME_DECIMALS)) + + def market_filling(self) -> Filling: + # FOK first: a webhook bot asking for 1 lot must get 1 lot or nothing. + # IOC could silently leave it with a partial fill it never asked for. + if self.filling_flags & _FILLING_FOK_FLAG: + return Filling.FOK + if self.filling_flags & _FILLING_IOC_FLAG: + return Filling.IOC + return Filling.RETURN + + def _volume_error(self, volume: float, reason: str) -> TradeError: + return TradeError( + ErrorKind.INVALID_VOLUME, + f"{self.name}: volume {volume} is {reason} " + f"[{self.volume_min}, {self.volume_max}] step {self.volume_step}", + ) diff --git a/src/PythonMetaTrader5/py.typed b/src/PythonMetaTrader5/py.typed new file mode 100644 index 0000000..e69de29 diff --git a/src/PythonMetaTrader5/result.py b/src/PythonMetaTrader5/result.py new file mode 100644 index 0000000..4038831 --- /dev/null +++ b/src/PythonMetaTrader5/result.py @@ -0,0 +1,41 @@ +"""Result type used at every port and use-case boundary. + +Chosen over exceptions at boundaries because a trading call has many *expected* +failures (market closed, no money, requote); an exception-based API lets callers +forget them, while a Result forces the caller to look at the outcome. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import Generic, TypeVar, Union + +T = TypeVar("T") +E = TypeVar("E") + + +@dataclass(frozen=True, slots=True) +class Ok(Generic[T]): + value: T + + def is_ok(self) -> bool: + return True + + def is_err(self) -> bool: + return False + + +@dataclass(frozen=True, slots=True) +class Err(Generic[E]): + error: E + + def is_ok(self) -> bool: + return False + + def is_err(self) -> bool: + return True + + +# Union (not PEP 604 `|`) because a generic alias built with `|` cannot be +# subscripted at runtime on Python 3.10. +Result = Union[Ok[T], Err[E]] # noqa: UP007 diff --git a/tests/unit/test_market.py b/tests/unit/test_market.py new file mode 100644 index 0000000..685b780 --- /dev/null +++ b/tests/unit/test_market.py @@ -0,0 +1,29 @@ +from PythonMetaTrader5.domain.market import Position, Tick +from PythonMetaTrader5.domain.orders import Side + + +def test_tick_quotes_the_price_a_side_trades_at() -> None: + tick = Tick(bid=1.1, ask=1.2) + assert tick.entry_price(Side.BUY) == 1.2 + assert tick.entry_price(Side.SELL) == 1.1 + assert tick.exit_price(Side.BUY) == 1.1 + assert tick.exit_price(Side.SELL) == 1.2 + + +def test_position_without_stops_reports_none() -> None: + position = Position( + ticket=7, + symbol="EURUSD", + side=Side.SELL, + volume=0.1, + price_open=1.1, + sl=None, + tp=None, + price_current=1.09, + profit=10.0, + time=0, + magic=0, + comment="", + ) + assert position.to_dict()["sl"] is None + assert position.to_dict()["side"] == "sell" diff --git a/tests/unit/test_orders.py b/tests/unit/test_orders.py new file mode 100644 index 0000000..ec67c67 --- /dev/null +++ b/tests/unit/test_orders.py @@ -0,0 +1,36 @@ +import pytest + +from PythonMetaTrader5.domain.errors import ErrorKind +from PythonMetaTrader5.domain.orders import Side, validate_comment +from PythonMetaTrader5.result import Err, Ok + + +@pytest.mark.parametrize( + ("text", "side"), + [("buy", Side.BUY), ("LONG", Side.BUY), (" sell ", Side.SELL), ("short", Side.SELL)], +) +def test_side_parses_aliases(text: str, side: Side) -> None: + assert Side.parse(text) == Ok(side) + assert Side.parse(side) == Ok(side) + + +def test_unknown_side_is_rejected() -> None: + result = Side.parse("hold") + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_ARGUMENT + + +def test_side_has_opposite() -> None: + assert Side.BUY.opposite is Side.SELL + assert Side.SELL.opposite is Side.BUY + + +def test_comment_within_terminal_limit_is_kept() -> None: + assert validate_comment(None) == Ok("") + assert validate_comment("x" * 31) == Ok("x" * 31) + + +def test_comment_over_terminal_limit_is_rejected_not_truncated() -> None: + result = validate_comment("x" * 32) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_ARGUMENT diff --git a/tests/unit/test_result.py b/tests/unit/test_result.py new file mode 100644 index 0000000..071b41b --- /dev/null +++ b/tests/unit/test_result.py @@ -0,0 +1,21 @@ +from PythonMetaTrader5.result import Err, Ok, Result + + +def describe(result: Result[int, str]) -> str: + match result: + case Ok(value): + return f"ok:{value}" + case Err(error): + return f"err:{error}" + + +def test_ok_and_err_are_pattern_matchable() -> None: + assert describe(Ok(3)) == "ok:3" + assert describe(Err("boom")) == "err:boom" + + +def test_ok_and_err_report_their_state() -> None: + assert Ok(1).is_ok() + assert not Ok(1).is_err() + assert Err("x").is_err() + assert not Err("x").is_ok() diff --git a/tests/unit/test_retcodes.py b/tests/unit/test_retcodes.py new file mode 100644 index 0000000..90b21fa --- /dev/null +++ b/tests/unit/test_retcodes.py @@ -0,0 +1,45 @@ +import pytest + +from PythonMetaTrader5.domain.errors import ErrorKind +from PythonMetaTrader5.domain.retcodes import Outcome, classify, error_for + + +@pytest.mark.parametrize("retcode", [10008, 10009, 10010]) +def test_done_placed_and_partial_are_success(retcode: int) -> None: + assert classify(retcode) is Outcome.SUCCESS + + +@pytest.mark.parametrize("retcode", [10004, 10020, 10021, 10024]) +def test_price_moves_and_throttling_are_retried(retcode: int) -> None: + assert classify(retcode) is Outcome.RETRY + + +@pytest.mark.parametrize("retcode", [10012, 10031]) +def test_timeout_and_lost_connection_are_never_retried(retcode: int) -> None: + # Retrying when the request may already be on the server risks a double fill. + assert classify(retcode) is Outcome.FAIL + assert error_for(retcode).kind is ErrorKind.OUTCOME_UNKNOWN + + +@pytest.mark.parametrize( + ("retcode", "kind"), + [ + (10018, ErrorKind.MARKET_CLOSED), + (10019, ErrorKind.NO_MONEY), + (10014, ErrorKind.INVALID_VOLUME), + (10016, ErrorKind.INVALID_STOPS), + (10015, ErrorKind.INVALID_PRICE), + (10030, ErrorKind.INVALID_FILLING), + (10027, ErrorKind.ALGO_TRADING_DISABLED), + (10017, ErrorKind.TRADE_DISABLED), + (10040, ErrorKind.LIMIT_REACHED), + (10006, ErrorKind.REJECTED), + (99999, ErrorKind.REJECTED), + ], +) +def test_permanent_failures_map_to_a_kind(retcode: int, kind: ErrorKind) -> None: + assert classify(retcode) is Outcome.FAIL + error = error_for(retcode) + assert error.kind is kind + assert error.retcode == retcode + assert error.message diff --git a/tests/unit/test_stops.py b/tests/unit/test_stops.py new file mode 100644 index 0000000..22d118d --- /dev/null +++ b/tests/unit/test_stops.py @@ -0,0 +1,37 @@ +import pytest + +from PythonMetaTrader5.domain.orders import Side +from PythonMetaTrader5.domain.stops import Stop +from PythonMetaTrader5.domain.symbol import SymbolSpec + +SPEC = SymbolSpec( + name="EURUSD", + digits=5, + point=0.00001, + tick_size=0.00001, + volume_min=0.01, + volume_max=100.0, + volume_step=0.01, + filling_flags=1, +) + + +def test_absolute_stop_is_only_normalized() -> None: + assert Stop.at_price(1.123456).stop_loss(Side.BUY, 1.2, SPEC) == 1.12346 + assert Stop.at_price(1.123456).take_profit(Side.SELL, 1.2, SPEC) == 1.12346 + + +@pytest.mark.parametrize( + ("side", "stop_loss", "take_profit"), + [(Side.BUY, 1.09, 1.115), (Side.SELL, 1.11, 1.085)], +) +def test_point_offsets_follow_trade_direction( + side: Side, stop_loss: float, take_profit: float +) -> None: + reference = 1.1 + assert Stop.points(1000).stop_loss(side, reference, SPEC) == stop_loss + assert Stop.points(1500).take_profit(side, reference, SPEC) == take_profit + + +def test_negative_offset_is_treated_as_distance() -> None: + assert Stop.points(-1000).stop_loss(Side.BUY, 1.1, SPEC) == 1.09 diff --git a/tests/unit/test_symbol.py b/tests/unit/test_symbol.py new file mode 100644 index 0000000..78e19f2 --- /dev/null +++ b/tests/unit/test_symbol.py @@ -0,0 +1,60 @@ +import pytest + +from PythonMetaTrader5.domain.errors import ErrorKind +from PythonMetaTrader5.domain.symbol import Filling, SymbolSpec +from PythonMetaTrader5.result import Err, Ok + + +def eurusd(**overrides: object) -> SymbolSpec: + fields: dict[str, object] = { + "name": "EURUSD", + "digits": 5, + "point": 0.00001, + "tick_size": 0.00001, + "volume_min": 0.01, + "volume_max": 100.0, + "volume_step": 0.01, + "filling_flags": 1, + } + fields.update(overrides) + return SymbolSpec(**fields) # type: ignore[arg-type] + + +def test_normalize_price_rounds_to_tick_without_float_noise() -> None: + assert eurusd().normalize_price(1.123456) == 1.12346 + assert eurusd().normalize_price(1.1) == 1.1 + + +def test_normalize_price_uses_tick_size_coarser_than_point() -> None: + index = eurusd(name="US500", digits=2, point=0.01, tick_size=0.25) + assert index.normalize_price(5780.13) == 5780.25 + + +def test_normalize_price_falls_back_to_point_when_tick_size_missing() -> None: + assert eurusd(tick_size=0.0).normalize_price(1.123456) == 1.12346 + + +@pytest.mark.parametrize("volume", [0.01, 0.1, 0.37, 100.0]) +def test_valid_volume_is_accepted(volume: float) -> None: + assert eurusd().validate_volume(volume) == Ok(volume) + + +@pytest.mark.parametrize("volume", [0.0, 0.005, 0.015, 100.01, -1.0]) +def test_invalid_volume_is_rejected(volume: float) -> None: + result = eurusd().validate_volume(volume) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_VOLUME + + +@pytest.mark.parametrize( + ("flags", "expected"), + [ + (1, Filling.FOK), + (2, Filling.IOC), + (3, Filling.FOK), + (0, Filling.RETURN), + (4, Filling.RETURN), + ], +) +def test_market_filling_prefers_fill_or_kill(flags: int, expected: Filling) -> None: + assert eurusd(filling_flags=flags).market_filling() is expected From 97ec9f0c332fb28be9a7a8fc1ceef80addfd13e4 Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 01:55:41 +0100 Subject: [PATCH 03/28] feat(application): add Trader use cases behind Terminal and Clock ports Ports exist only for the two process boundaries: the MT5 terminal and time. - open_position: SL/TP as prices (floats) or Stop.points distances, requotes retried with a fresh quote at most RetryPolicy.attempts times. 2.x looped forever on any unknown retcode (e.g. NO_MONEY), sending an order every 0.5 s. - place_limit_order: RETURN filling, success on PLACED (10008). - close_positions: closes each position on its own symbol. 2.x priced every close with the `symbol` argument, so close-by-ticket with symbol=None crashed. - Batch operations return BatchFailure listing what succeeded and what failed, instead of a boolean that hid partial closes. - magic filters for close/cancel/queries so a bot never touches manual trades. --- src/PythonMetaTrader5/application/__init__.py | 1 + .../application/execution.py | 67 +++++ src/PythonMetaTrader5/application/ports.py | 48 +++ src/PythonMetaTrader5/application/trader.py | 281 ++++++++++++++++++ src/PythonMetaTrader5/domain/errors.py | 5 +- src/PythonMetaTrader5/domain/requests.py | 32 ++ src/PythonMetaTrader5/domain/retcodes.py | 4 + tests/__init__.py | 0 tests/integration/__init__.py | 0 tests/unit/__init__.py | 0 tests/unit/conftest.py | 23 ++ tests/unit/fakes.py | 118 ++++++++ tests/unit/test_close_positions.py | 83 ++++++ tests/unit/test_failure_paths.py | 80 +++++ tests/unit/test_open_position.py | 104 +++++++ tests/unit/test_pending_orders.py | 77 +++++ 16 files changed, 922 insertions(+), 1 deletion(-) create mode 100644 src/PythonMetaTrader5/application/__init__.py create mode 100644 src/PythonMetaTrader5/application/execution.py create mode 100644 src/PythonMetaTrader5/application/ports.py create mode 100644 src/PythonMetaTrader5/application/trader.py create mode 100644 src/PythonMetaTrader5/domain/requests.py create mode 100644 tests/__init__.py create mode 100644 tests/integration/__init__.py create mode 100644 tests/unit/__init__.py create mode 100644 tests/unit/conftest.py create mode 100644 tests/unit/fakes.py create mode 100644 tests/unit/test_close_positions.py create mode 100644 tests/unit/test_failure_paths.py create mode 100644 tests/unit/test_open_position.py create mode 100644 tests/unit/test_pending_orders.py diff --git a/src/PythonMetaTrader5/application/__init__.py b/src/PythonMetaTrader5/application/__init__.py new file mode 100644 index 0000000..c356dd4 --- /dev/null +++ b/src/PythonMetaTrader5/application/__init__.py @@ -0,0 +1 @@ +"""Use cases and the ports they need from the outside world.""" diff --git a/src/PythonMetaTrader5/application/execution.py b/src/PythonMetaTrader5/application/execution.py new file mode 100644 index 0000000..71fdf7b --- /dev/null +++ b/src/PythonMetaTrader5/application/execution.py @@ -0,0 +1,67 @@ +"""Sending a request with a bounded, outcome-aware retry loop.""" + +from __future__ import annotations + +import logging +from collections.abc import Callable +from dataclasses import dataclass, replace + +from PythonMetaTrader5.application.ports import Clock, Terminal +from PythonMetaTrader5.domain.errors import ErrorKind, TradeError +from PythonMetaTrader5.domain.market import TradeReceipt +from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest +from PythonMetaTrader5.domain.retcodes import Outcome, classify, error_for +from PythonMetaTrader5.result import Err, Result + +log = logging.getLogger("PythonMetaTrader5") + +RequestFactory = Callable[[], Result[OrderRequest | CancelRequest, TradeError]] + + +@dataclass(frozen=True, slots=True) +class RetryPolicy: + attempts: int = 3 + delay_seconds: float = 0.5 + + def __post_init__(self) -> None: + # Misconfiguration is a programming error, not a market outcome, so it + # fails loudly at construction instead of travelling as a Result. + if self.attempts < 1 or self.delay_seconds < 0: + raise ValueError(f"invalid retry policy: {self}") + + +def execute( + terminal: Terminal, clock: Clock, build: RequestFactory, policy: RetryPolicy +) -> Result[TradeReceipt, TradeError]: + """Rebuild and send the request until it succeeds, fails, or attempts run out. + + The request is rebuilt on every attempt so a requote is answered with the + current price instead of re-sending the stale one. + """ + last: TradeReceipt | None = None + for attempt in range(1, policy.attempts + 1): + request = build() + if isinstance(request, Err): + return request + sent = terminal.send(request.value) + if isinstance(sent, Err): + return sent + last = sent.value + outcome = classify(last.retcode) + if outcome is Outcome.SUCCESS: + return sent + if outcome is Outcome.FAIL: + return Err(replace(error_for(last.retcode), receipt=last)) + log.warning("retcode %s on attempt %s/%s", last.retcode, attempt, policy.attempts) + if attempt < policy.attempts: + clock.sleep(policy.delay_seconds) + if last is None: # pragma: no cover - range(1, attempts + 1) is never empty + raise AssertionError("retry loop ran zero times") + return Err( + TradeError( + ErrorKind.RETRIES_EXHAUSTED, + f"gave up after {policy.attempts} attempts: {error_for(last.retcode).message}", + retcode=last.retcode, + receipt=last, + ) + ) diff --git a/src/PythonMetaTrader5/application/ports.py b/src/PythonMetaTrader5/application/ports.py new file mode 100644 index 0000000..a498bbf --- /dev/null +++ b/src/PythonMetaTrader5/application/ports.py @@ -0,0 +1,48 @@ +"""The only two process boundaries of the library: the MT5 terminal and time.""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from typing import Protocol + +from PythonMetaTrader5.domain.errors import TradeError +from PythonMetaTrader5.domain.market import PendingOrder, Position, Tick, TradeReceipt +from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest +from PythonMetaTrader5.domain.symbol import SymbolSpec +from PythonMetaTrader5.result import Result + + +@dataclass(frozen=True, slots=True) +class Credentials: + login: int + # repr=False keeps the password out of logs, tracebacks and debugger dumps. + password: str = field(repr=False) + server: str + path: str | None = None + timeout_ms: int = 60_000 + + +class Terminal(Protocol): + def connect(self, credentials: Credentials) -> Result[None, TradeError]: ... + + def shutdown(self) -> None: ... + + def symbol(self, name: str) -> Result[SymbolSpec, TradeError]: ... + + def tick(self, name: str) -> Result[Tick, TradeError]: ... + + def send(self, request: OrderRequest | CancelRequest) -> Result[TradeReceipt, TradeError]: + """Err only when the request could not be delivered; broker refusals are receipts.""" + ... + + def positions( + self, *, symbol: str | None = None, ticket: int | None = None + ) -> Result[list[Position], TradeError]: ... + + def pending_orders( + self, *, symbol: str | None = None + ) -> Result[list[PendingOrder], TradeError]: ... + + +class Clock(Protocol): + def sleep(self, seconds: float) -> None: ... diff --git a/src/PythonMetaTrader5/application/trader.py b/src/PythonMetaTrader5/application/trader.py new file mode 100644 index 0000000..cdfc5a4 --- /dev/null +++ b/src/PythonMetaTrader5/application/trader.py @@ -0,0 +1,281 @@ +"""Trading use cases: open, close, place and cancel orders, query state.""" + +from __future__ import annotations + +from collections.abc import Callable, Iterable +from dataclasses import dataclass, replace +from typing import Protocol, TypeVar + +from PythonMetaTrader5.application.execution import RetryPolicy, execute +from PythonMetaTrader5.application.ports import Clock, Terminal +from PythonMetaTrader5.domain.errors import TradeError +from PythonMetaTrader5.domain.market import PendingKind, PendingOrder, Position, TradeReceipt +from PythonMetaTrader5.domain.orders import Side, validate_comment +from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest +from PythonMetaTrader5.domain.stops import Stop +from PythonMetaTrader5.domain.symbol import Filling, SymbolSpec +from PythonMetaTrader5.result import Err, Ok, Result + +StopInput = Stop | float | None + + +class _HasMagic(Protocol): + @property + def magic(self) -> int: ... + + +_M = TypeVar("_M", bound=_HasMagic) + + +@dataclass(frozen=True, slots=True) +class BatchFailure: + """Some items of a batch (close all / cancel all) failed; others may have succeeded.""" + + succeeded: tuple[TradeReceipt, ...] + errors: tuple[TradeError, ...] + + def __str__(self) -> str: + return f"{len(self.errors)} failed, {len(self.succeeded)} succeeded: " + "; ".join( + str(e) for e in self.errors + ) + + +@dataclass(frozen=True, slots=True) +class _Entry: + """Validated parameters shared by market and pending entries.""" + + spec: SymbolSpec + side: Side + volume: float + comment: str + + +class Trader: + def __init__( + self, + terminal: Terminal, + clock: Clock, + *, + magic: int = 0, + deviation: int = 10, + retry: RetryPolicy | None = None, + ) -> None: + self._terminal = terminal + self._clock = clock + self._magic = magic + self._deviation = deviation + self._retry = retry or RetryPolicy() + + # ------------------------------------------------------------------ entries + + def open_position( + self, + symbol: str, + side: Side | str, + volume: float, + *, + sl: StopInput = None, + tp: StopInput = None, + price: float | None = None, + comment: str | None = None, + ) -> Result[TradeReceipt, TradeError]: + """Open a market position; ``sl``/``tp`` floats are prices, ``Stop.points`` distances. + + Without ``price`` the current quote is used and requotes are retried with a + fresh quote. An explicit ``price`` is sent once: re-sending the same price + after a requote cannot succeed. + """ + entry = self._validate_entry(symbol, side, volume, comment) + if isinstance(entry, Err): + return entry + e = entry.value + + def build() -> Result[OrderRequest | CancelRequest, TradeError]: + if price is not None: + reference = e.spec.normalize_price(price) + else: + tick = self._terminal.tick(symbol) + if isinstance(tick, Err): + return tick + reference = tick.value.entry_price(e.side) + return Ok( + self._entry_request( + e, reference, sl=sl, tp=tp, filling=e.spec.market_filling(), pending=None + ) + ) + + policy = self._retry if price is None else replace(self._retry, attempts=1) + return execute(self._terminal, self._clock, build, policy) + + def place_limit_order( + self, + symbol: str, + side: Side | str, + volume: float, + price: float, + *, + sl: StopInput = None, + tp: StopInput = None, + comment: str | None = None, + ) -> Result[TradeReceipt, TradeError]: + """Place a BUY/SELL LIMIT at ``price``; point stops are measured from that level. + + A limit on the wrong side of the market is refused by the server + (INVALID_PRICE) rather than converted into a market order. + """ + entry = self._validate_entry(symbol, side, volume, comment) + if isinstance(entry, Err): + return entry + e = entry.value + level = e.spec.normalize_price(price) + # RETURN: a resting order must keep its unfilled remainder; FOK/IOC would + # cancel it the moment it is not immediately fillable. + request = self._entry_request( + e, level, sl=sl, tp=tp, filling=Filling.RETURN, pending=PendingKind.LIMIT + ) + return execute(self._terminal, self._clock, lambda: Ok(request), self._retry) + + # ------------------------------------------------------------------- exits + + def close_positions( + self, + symbol: str | None = None, + *, + ticket: int | None = None, + magic: int | None = None, + comment: str | None = None, + ) -> Result[list[TradeReceipt], BatchFailure]: + """Close matching positions; ``ticket`` takes precedence over ``symbol``.""" + text = validate_comment(comment) + if isinstance(text, Err): + return Err(BatchFailure((), (text.error,))) + listed = self.positions(None if ticket is not None else symbol, ticket=ticket, magic=magic) + if isinstance(listed, Err): + return Err(BatchFailure((), (listed.error,))) + return self._batch(listed.value, lambda p: self._close_one(p, text.value)) + + def cancel_pending_orders( + self, symbol: str | None = None, *, magic: int | None = None + ) -> Result[list[TradeReceipt], BatchFailure]: + listed = self.pending_orders(symbol, magic=magic) + if isinstance(listed, Err): + return Err(BatchFailure((), (listed.error,))) + return self._batch(listed.value, self._cancel_one) + + # ----------------------------------------------------------------- queries + + def positions( + self, symbol: str | None = None, *, ticket: int | None = None, magic: int | None = None + ) -> Result[list[Position], TradeError]: + listed = self._terminal.positions(symbol=symbol, ticket=ticket) + return listed if isinstance(listed, Err) else Ok(_with_magic(listed.value, magic)) + + def pending_orders( + self, symbol: str | None = None, *, magic: int | None = None + ) -> Result[list[PendingOrder], TradeError]: + listed = self._terminal.pending_orders(symbol=symbol) + return listed if isinstance(listed, Err) else Ok(_with_magic(listed.value, magic)) + + def shutdown(self) -> None: + self._terminal.shutdown() + + # ----------------------------------------------------------------- helpers + + def _validate_entry( + self, symbol: str, side: Side | str, volume: float, comment: str | None + ) -> Result[_Entry, TradeError]: + parsed_side = Side.parse(side) + if isinstance(parsed_side, Err): + return parsed_side + text = validate_comment(comment) + if isinstance(text, Err): + return text + spec = self._terminal.symbol(symbol) + if isinstance(spec, Err): + return spec + lots = spec.value.validate_volume(float(volume)) + if isinstance(lots, Err): + return lots + return Ok(_Entry(spec.value, parsed_side.value, lots.value, text.value)) + + def _entry_request( + self, + e: _Entry, + reference: float, + *, + sl: StopInput, + tp: StopInput, + filling: Filling, + pending: PendingKind | None, + ) -> OrderRequest: + stop_loss, take_profit = _as_stop(sl), _as_stop(tp) + return OrderRequest( + symbol=e.spec.name, + side=e.side, + volume=e.volume, + price=reference, + filling=filling, + deviation=self._deviation, + magic=self._magic, + comment=e.comment, + sl=stop_loss.stop_loss(e.side, reference, e.spec) if stop_loss else None, + tp=take_profit.take_profit(e.side, reference, e.spec) if take_profit else None, + pending=pending, + ) + + def _close_one(self, position: Position, comment: str) -> Result[TradeReceipt, TradeError]: + spec = self._terminal.symbol(position.symbol) + if isinstance(spec, Err): + return spec + side = position.side.opposite + + def build() -> Result[OrderRequest | CancelRequest, TradeError]: + tick = self._terminal.tick(position.symbol) + if isinstance(tick, Err): + return tick + return Ok( + OrderRequest( + symbol=position.symbol, + side=side, + volume=position.volume, + price=tick.value.entry_price(side), + filling=spec.value.market_filling(), + deviation=self._deviation, + magic=self._magic, + comment=comment, + position=position.ticket, + ) + ) + + return execute(self._terminal, self._clock, build, self._retry) + + def _cancel_one(self, order: PendingOrder) -> Result[TradeReceipt, TradeError]: + request = CancelRequest(order=order.ticket) + return execute(self._terminal, self._clock, lambda: Ok(request), self._retry) + + def _batch( + self, + items: Iterable[Position] | Iterable[PendingOrder], + action: Callable[..., Result[TradeReceipt, TradeError]], + ) -> Result[list[TradeReceipt], BatchFailure]: + succeeded: list[TradeReceipt] = [] + errors: list[TradeError] = [] + for item in items: + match action(item): + case Ok(receipt): + succeeded.append(receipt) + case Err(error): + errors.append(replace(error, ticket=item.ticket)) + if errors: + return Err(BatchFailure(tuple(succeeded), tuple(errors))) + return Ok(succeeded) + + +def _as_stop(value: StopInput) -> Stop | None: + if value is None or isinstance(value, Stop): + return value + return Stop.at_price(value) + + +def _with_magic(items: list[_M], magic: int | None) -> list[_M]: + return items if magic is None else [item for item in items if item.magic == magic] diff --git a/src/PythonMetaTrader5/domain/errors.py b/src/PythonMetaTrader5/domain/errors.py index 6147f62..68063c7 100644 --- a/src/PythonMetaTrader5/domain/errors.py +++ b/src/PythonMetaTrader5/domain/errors.py @@ -38,7 +38,10 @@ class TradeError: retcode: int | None = None # Kept so callers (and the 2.x facade) can inspect the broker's raw answer. receipt: TradeReceipt | None = None + # Set when the failure concerns one position/order of a batch operation. + ticket: int | None = None def __str__(self) -> str: code = f" (retcode {self.retcode})" if self.retcode is not None else "" - return f"{self.kind.value}: {self.message}{code}" + ticket = f" [ticket {self.ticket}]" if self.ticket is not None else "" + return f"{self.kind.value}: {self.message}{code}{ticket}" diff --git a/src/PythonMetaTrader5/domain/requests.py b/src/PythonMetaTrader5/domain/requests.py new file mode 100644 index 0000000..fe903eb --- /dev/null +++ b/src/PythonMetaTrader5/domain/requests.py @@ -0,0 +1,32 @@ +"""Trade requests in domain terms; the terminal adapter translates them to MT5.""" + +from __future__ import annotations + +from dataclasses import dataclass + +from PythonMetaTrader5.domain.market import PendingKind +from PythonMetaTrader5.domain.orders import Side +from PythonMetaTrader5.domain.symbol import Filling + + +@dataclass(frozen=True, slots=True) +class OrderRequest: + symbol: str + side: Side + volume: float + price: float + filling: Filling + deviation: int + magic: int + comment: str = "" + sl: float | None = None + tp: float | None = None + # Ticket of the position being closed; None opens a new position. + position: int | None = None + # None means a market deal; a kind means a pending order at `price`. + pending: PendingKind | None = None + + +@dataclass(frozen=True, slots=True) +class CancelRequest: + order: int diff --git a/src/PythonMetaTrader5/domain/retcodes.py b/src/PythonMetaTrader5/domain/retcodes.py index c811b74..a3611df 100644 --- a/src/PythonMetaTrader5/domain/retcodes.py +++ b/src/PythonMetaTrader5/domain/retcodes.py @@ -27,6 +27,7 @@ class Outcome(Enum): _RETRY = frozenset({10004, 10020, 10021, 10024}) _FAILURES: dict[int, tuple[ErrorKind, str]] = { + 10004: (ErrorKind.REJECTED, "requote"), 10006: (ErrorKind.REJECTED, "request rejected by the server"), 10007: (ErrorKind.REJECTED, "request cancelled by the trader"), 10011: (ErrorKind.REJECTED, "request processing error"), @@ -38,7 +39,10 @@ class Outcome(Enum): 10017: (ErrorKind.TRADE_DISABLED, "trading is disabled"), 10018: (ErrorKind.MARKET_CLOSED, "market is closed"), 10019: (ErrorKind.NO_MONEY, "not enough money"), + 10020: (ErrorKind.REJECTED, "prices changed"), + 10021: (ErrorKind.NO_PRICE, "no quotes to process the request"), 10022: (ErrorKind.INVALID_ARGUMENT, "invalid order expiration"), + 10024: (ErrorKind.REJECTED, "too many requests"), 10026: (ErrorKind.ALGO_TRADING_DISABLED, "autotrading disabled by the server"), 10027: (ErrorKind.ALGO_TRADING_DISABLED, "enable Algo Trading in the MetaTrader 5 terminal"), 10028: (ErrorKind.REJECTED, "request locked for processing"), diff --git a/tests/__init__.py b/tests/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/integration/__init__.py b/tests/integration/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/unit/__init__.py b/tests/unit/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/unit/conftest.py b/tests/unit/conftest.py new file mode 100644 index 0000000..387da29 --- /dev/null +++ b/tests/unit/conftest.py @@ -0,0 +1,23 @@ +import pytest + +from PythonMetaTrader5.application.trader import Trader + +from .fakes import FakeClock, FakeTerminal + + +@pytest.fixture +def terminal() -> FakeTerminal: + fake = FakeTerminal() + fake.quote("EURUSD", (1.10000, 1.10010)) + fake.quote("XAUUSD", (2400.00, 2400.50)) + return fake + + +@pytest.fixture +def clock() -> FakeClock: + return FakeClock() + + +@pytest.fixture +def trader(terminal: FakeTerminal, clock: FakeClock) -> Trader: + return Trader(terminal, clock, magic=42) diff --git a/tests/unit/fakes.py b/tests/unit/fakes.py new file mode 100644 index 0000000..9aef8c3 --- /dev/null +++ b/tests/unit/fakes.py @@ -0,0 +1,118 @@ +"""In-memory stand-ins for the two process boundaries (terminal, clock).""" + +from __future__ import annotations + +from collections import deque +from dataclasses import dataclass, field + +from PythonMetaTrader5.application.ports import Credentials +from PythonMetaTrader5.domain.errors import ErrorKind, TradeError +from PythonMetaTrader5.domain.market import PendingOrder, Position, Tick, TradeReceipt +from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest +from PythonMetaTrader5.domain.symbol import SymbolSpec +from PythonMetaTrader5.result import Err, Ok, Result + +EURUSD = SymbolSpec( + name="EURUSD", + digits=5, + point=0.00001, + tick_size=0.00001, + volume_min=0.01, + volume_max=100.0, + volume_step=0.01, + filling_flags=1, +) +XAUUSD = SymbolSpec( + name="XAUUSD", + digits=2, + point=0.01, + tick_size=0.01, + volume_min=0.01, + volume_max=50.0, + volume_step=0.01, + filling_flags=2, +) + + +def receipt(retcode: int = 10009, price: float = 0.0) -> TradeReceipt: + return TradeReceipt( + retcode=retcode, + deal=1, + order=1, + volume=0.1, + price=price, + bid=0.0, + ask=0.0, + comment="", + request_id=1, + ) + + +@dataclass +class FakeTerminal: + specs: dict[str, SymbolSpec] = field( + default_factory=lambda: {"EURUSD": EURUSD, "XAUUSD": XAUUSD} + ) + ticks: dict[str, deque[Tick]] = field(default_factory=dict) + retcodes: deque[int] = field(default_factory=deque) + open_positions: list[Position] = field(default_factory=list) + open_orders: list[PendingOrder] = field(default_factory=list) + send_failure: TradeError | None = None + connect_failure: TradeError | None = None + sent: list[OrderRequest | CancelRequest] = field(default_factory=list) + connected_with: list[Credentials] = field(default_factory=list) + shut_down: bool = False + + def quote(self, symbol: str, *ticks: tuple[float, float]) -> None: + self.ticks[symbol] = deque(Tick(bid, ask) for bid, ask in ticks) + + def connect(self, credentials: Credentials) -> Result[None, TradeError]: + self.connected_with.append(credentials) + return Err(self.connect_failure) if self.connect_failure else Ok(None) + + def shutdown(self) -> None: + self.shut_down = True + + def symbol(self, name: str) -> Result[SymbolSpec, TradeError]: + if name not in self.specs: + return Err(TradeError(ErrorKind.SYMBOL_NOT_FOUND, name)) + return Ok(self.specs[name]) + + def tick(self, name: str) -> Result[Tick, TradeError]: + queue = self.ticks.get(name) + if not queue: + return Err(TradeError(ErrorKind.NO_PRICE, name)) + # The last quote sticks, earlier ones are consumed one per call. + return Ok(queue.popleft() if len(queue) > 1 else queue[0]) + + def send(self, request: OrderRequest | CancelRequest) -> Result[TradeReceipt, TradeError]: + self.sent.append(request) + if self.send_failure: + return Err(self.send_failure) + code = self.retcodes.popleft() if self.retcodes else 10009 + price = request.price if isinstance(request, OrderRequest) else 0.0 + return Ok(receipt(code, price)) + + def positions( + self, *, symbol: str | None = None, ticket: int | None = None + ) -> Result[list[Position], TradeError]: + return Ok( + [ + p + for p in self.open_positions + if (symbol is None or p.symbol == symbol) and (ticket is None or p.ticket == ticket) + ] + ) + + def pending_orders( + self, *, symbol: str | None = None + ) -> Result[list[PendingOrder], TradeError]: + return Ok([o for o in self.open_orders if symbol is None or o.symbol == symbol]) + + +@dataclass +class FakeClock: + sleeps: list[float] = field(default_factory=list) + + def sleep(self, seconds: float) -> None: + self.sleeps.append(seconds) diff --git a/tests/unit/test_close_positions.py b/tests/unit/test_close_positions.py new file mode 100644 index 0000000..faeaae2 --- /dev/null +++ b/tests/unit/test_close_positions.py @@ -0,0 +1,83 @@ +from PythonMetaTrader5.application.trader import BatchFailure, Trader +from PythonMetaTrader5.domain.errors import ErrorKind +from PythonMetaTrader5.domain.market import Position +from PythonMetaTrader5.domain.orders import Side +from PythonMetaTrader5.domain.requests import OrderRequest +from PythonMetaTrader5.result import Err, Ok + +from .fakes import FakeTerminal + + +def position(ticket: int, symbol: str, side: Side, magic: int = 42) -> Position: + return Position( + ticket=ticket, + symbol=symbol, + side=side, + volume=0.2, + price_open=1.0, + sl=None, + tp=None, + price_current=1.0, + profit=0.0, + time=0, + magic=magic, + comment="", + ) + + +def sent_orders(terminal: FakeTerminal) -> list[OrderRequest]: + orders = [r for r in terminal.sent if isinstance(r, OrderRequest)] + assert len(orders) == len(terminal.sent) + return orders + + +def test_each_position_is_closed_on_its_own_symbol(trader: Trader, terminal: FakeTerminal) -> None: + terminal.open_positions = [position(1, "EURUSD", Side.BUY), position(2, "XAUUSD", Side.SELL)] + result = trader.close_positions() + assert isinstance(result, Ok) + assert len(result.value) == 2 + first, second = sent_orders(terminal) + assert (first.symbol, first.side, first.price, first.position) == ("EURUSD", Side.SELL, 1.1, 1) + assert (second.symbol, second.side, second.price, second.position) == ( + "XAUUSD", + Side.BUY, + 2400.5, + 2, + ) + assert first.volume == 0.2 + + +def test_close_by_ticket_ignores_the_symbol_argument( + trader: Trader, terminal: FakeTerminal +) -> None: + terminal.open_positions = [position(1, "EURUSD", Side.BUY), position(2, "XAUUSD", Side.SELL)] + assert isinstance(trader.close_positions("EURUSD", ticket=2), Ok) + (request,) = sent_orders(terminal) + assert request.symbol == "XAUUSD" + + +def test_nothing_to_close_is_success(trader: Trader) -> None: + assert trader.close_positions("EURUSD") == Ok([]) + + +def test_magic_filter_leaves_foreign_positions_open(trader: Trader, terminal: FakeTerminal) -> None: + terminal.open_positions = [ + position(1, "EURUSD", Side.BUY, magic=7), + position(2, "EURUSD", Side.BUY, magic=42), + ] + trader.close_positions("EURUSD", magic=42) + assert [r.position for r in sent_orders(terminal)] == [2] + + +def test_partial_failure_reports_what_closed_and_what_did_not( + trader: Trader, terminal: FakeTerminal +) -> None: + terminal.open_positions = [position(1, "EURUSD", Side.BUY), position(2, "EURUSD", Side.BUY)] + terminal.retcodes.extend([10009, 10018]) + result = trader.close_positions("EURUSD") + assert isinstance(result, Err) + failure = result.error + assert isinstance(failure, BatchFailure) + assert len(failure.succeeded) == 1 + (error,) = failure.errors + assert (error.kind, error.ticket) == (ErrorKind.MARKET_CLOSED, 2) diff --git a/tests/unit/test_failure_paths.py b/tests/unit/test_failure_paths.py new file mode 100644 index 0000000..0e59136 --- /dev/null +++ b/tests/unit/test_failure_paths.py @@ -0,0 +1,80 @@ +import pytest + +from PythonMetaTrader5.application.execution import RetryPolicy +from PythonMetaTrader5.application.trader import BatchFailure, Trader +from PythonMetaTrader5.domain.errors import ErrorKind, TradeError +from PythonMetaTrader5.domain.market import Position +from PythonMetaTrader5.domain.orders import Side +from PythonMetaTrader5.result import Err + +from .fakes import FakeTerminal, receipt + + +def btc_position() -> Position: + return Position( + ticket=9, + symbol="BTCUSD", + side=Side.BUY, + volume=0.1, + price_open=1.0, + sl=None, + tp=None, + price_current=1.0, + profit=0.0, + time=0, + magic=0, + comment="", + ) + + +@pytest.mark.parametrize("policy", [{"attempts": 0}, {"delay_seconds": -1.0}]) +def test_nonsensical_retry_policy_fails_at_construction(policy: dict[str, float]) -> None: + with pytest.raises(ValueError, match="invalid retry policy"): + RetryPolicy(**policy) # type: ignore[arg-type] + + +def test_errors_render_kind_retcode_and_ticket() -> None: + error = TradeError(ErrorKind.MARKET_CLOSED, "market is closed", retcode=10018, ticket=3) + assert str(error) == "market_closed: market is closed (retcode 10018) [ticket 3]" + failure = BatchFailure((receipt(),), (error,)) + assert str(failure).startswith("1 failed, 1 succeeded: market_closed") + + +def test_close_reports_unknown_symbol_and_missing_quote( + trader: Trader, terminal: FakeTerminal +) -> None: + terminal.open_positions = [btc_position()] + result = trader.close_positions() + assert isinstance(result, Err) + assert result.error.errors[0].kind is ErrorKind.SYMBOL_NOT_FOUND + terminal.specs["BTCUSD"] = terminal.specs["EURUSD"] + result = trader.close_positions() + assert isinstance(result, Err) + assert result.error.errors[0].kind is ErrorKind.NO_PRICE + + +def test_close_rejects_overlong_comment_before_touching_positions( + trader: Trader, terminal: FakeTerminal +) -> None: + terminal.open_positions = [btc_position()] + result = trader.close_positions(comment="c" * 32) + assert isinstance(result, Err) + assert result.error.errors[0].kind is ErrorKind.INVALID_ARGUMENT + assert terminal.sent == [] + + +class BrokenListing(FakeTerminal): + def positions(self, **_: object) -> Err[TradeError]: # type: ignore[override] + return Err(TradeError(ErrorKind.TERMINAL_ERROR, "positions_get failed")) + + def pending_orders(self, **_: object) -> Err[TradeError]: # type: ignore[override] + return Err(TradeError(ErrorKind.TERMINAL_ERROR, "orders_get failed")) + + +def test_listing_failures_surface_as_batch_failures(clock: object) -> None: + trader = Trader(BrokenListing(), clock) # type: ignore[arg-type] + for result in (trader.close_positions(), trader.cancel_pending_orders()): + assert isinstance(result, Err) + assert result.error.errors[0].kind is ErrorKind.TERMINAL_ERROR + assert isinstance(trader.positions(), Err) + assert isinstance(trader.pending_orders(), Err) diff --git a/tests/unit/test_open_position.py b/tests/unit/test_open_position.py new file mode 100644 index 0000000..48b861a --- /dev/null +++ b/tests/unit/test_open_position.py @@ -0,0 +1,104 @@ +from PythonMetaTrader5.application.trader import Trader +from PythonMetaTrader5.domain.errors import ErrorKind, TradeError +from PythonMetaTrader5.domain.orders import Side +from PythonMetaTrader5.domain.requests import OrderRequest +from PythonMetaTrader5.domain.stops import Stop +from PythonMetaTrader5.domain.symbol import Filling +from PythonMetaTrader5.result import Err, Ok + +from .fakes import FakeClock, FakeTerminal + + +def only_request(terminal: FakeTerminal) -> OrderRequest: + (request,) = terminal.sent + assert isinstance(request, OrderRequest) + return request + + +def test_buy_uses_ask_and_resolves_point_stops(trader: Trader, terminal: FakeTerminal) -> None: + result = trader.open_position( + "EURUSD", "buy", 0.1, sl=Stop.points(1000), tp=Stop.points(1500), comment="hook" + ) + assert isinstance(result, Ok) + request = only_request(terminal) + assert (request.side, request.price, request.volume) == (Side.BUY, 1.1001, 0.1) + assert (request.sl, request.tp) == (1.0901, 1.1151) + assert (request.filling, request.magic, request.comment) == (Filling.FOK, 42, "hook") + assert request.position is None + + +def test_sell_uses_bid_and_plain_float_stops_are_prices( + trader: Trader, terminal: FakeTerminal +) -> None: + trader.open_position("XAUUSD", Side.SELL, 0.1, sl=2410.123, tp=2390.0) + request = only_request(terminal) + assert (request.price, request.sl, request.tp) == (2400.0, 2410.12, 2390.0) + assert request.filling is Filling.IOC + + +def test_requote_is_retried_with_a_fresh_quote( + trader: Trader, terminal: FakeTerminal, clock: FakeClock +) -> None: + terminal.quote("EURUSD", (1.1, 1.1001), (1.1002, 1.1003)) + terminal.retcodes.extend([10004, 10009]) + assert isinstance(trader.open_position("EURUSD", "buy", 0.1), Ok) + assert [r.price for r in terminal.sent] == [1.1001, 1.1003] # type: ignore[union-attr] + assert clock.sleeps == [0.5] + + +def test_retries_are_bounded(trader: Trader, terminal: FakeTerminal) -> None: + terminal.retcodes.extend([10004] * 10) + result = trader.open_position("EURUSD", "buy", 0.1) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.RETRIES_EXHAUSTED + assert result.error.retcode == 10004 + assert len(terminal.sent) == 3 + + +def test_permanent_failure_is_not_retried(trader: Trader, terminal: FakeTerminal) -> None: + terminal.retcodes.append(10018) + result = trader.open_position("EURUSD", "buy", 0.1) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.MARKET_CLOSED + assert result.error.receipt is not None + assert len(terminal.sent) == 1 + + +def test_transport_failure_is_returned_without_retry( + trader: Trader, terminal: FakeTerminal +) -> None: + terminal.send_failure = TradeError(ErrorKind.TERMINAL_ERROR, "IPC broken") + result = trader.open_position("EURUSD", "buy", 0.1) + assert result == Err(terminal.send_failure) + assert len(terminal.sent) == 1 + + +def test_explicit_price_is_normalized_and_sent_once(trader: Trader, terminal: FakeTerminal) -> None: + terminal.retcodes.append(10004) + result = trader.open_position("EURUSD", "buy", 0.1, price=1.123456, sl=Stop.points(100)) + assert isinstance(result, Err) + request = only_request(terminal) + assert (request.price, request.sl) == (1.12346, 1.12246) + + +def test_invalid_input_never_reaches_the_terminal(trader: Trader, terminal: FakeTerminal) -> None: + cases = [ + (trader.open_position("EURUSD", "hold", 0.1), ErrorKind.INVALID_ARGUMENT), + (trader.open_position("EURUSD", "buy", 0.015), ErrorKind.INVALID_VOLUME), + (trader.open_position("NOPE", "buy", 0.1), ErrorKind.SYMBOL_NOT_FOUND), + ( + trader.open_position("EURUSD", "buy", 0.1, comment="c" * 40), + ErrorKind.INVALID_ARGUMENT, + ), + ] + for result, kind in cases: + assert isinstance(result, Err) + assert result.error.kind is kind + assert terminal.sent == [] + + +def test_missing_quote_is_an_error(trader: Trader, terminal: FakeTerminal) -> None: + terminal.ticks.clear() + result = trader.open_position("EURUSD", "buy", 0.1) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.NO_PRICE diff --git a/tests/unit/test_pending_orders.py b/tests/unit/test_pending_orders.py new file mode 100644 index 0000000..c360c59 --- /dev/null +++ b/tests/unit/test_pending_orders.py @@ -0,0 +1,77 @@ +from PythonMetaTrader5.application.trader import Trader +from PythonMetaTrader5.domain.errors import ErrorKind +from PythonMetaTrader5.domain.market import PendingKind, PendingOrder +from PythonMetaTrader5.domain.orders import Side +from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest +from PythonMetaTrader5.domain.stops import Stop +from PythonMetaTrader5.domain.symbol import Filling +from PythonMetaTrader5.result import Err, Ok + +from .fakes import FakeTerminal + + +def test_limit_order_is_placed_at_its_level(trader: Trader, terminal: FakeTerminal) -> None: + terminal.retcodes.append(10008) + result = trader.place_limit_order("EURUSD", "buy", 0.1, 1.0950004, sl=Stop.points(50)) + assert isinstance(result, Ok) + (request,) = terminal.sent + assert isinstance(request, OrderRequest) + assert (request.pending, request.price, request.sl) == (PendingKind.LIMIT, 1.095, 1.0945) + assert request.filling is Filling.RETURN + + +def test_limit_order_rejected_by_server_is_an_error(trader: Trader, terminal: FakeTerminal) -> None: + terminal.retcodes.append(10015) + result = trader.place_limit_order("EURUSD", "sell", 0.1, 1.0) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_PRICE + + +def order(ticket: int, symbol: str, magic: int = 42) -> PendingOrder: + return PendingOrder( + ticket=ticket, + symbol=symbol, + side=Side.BUY, + kind=PendingKind.LIMIT, + volume=0.1, + price=1.0, + magic=magic, + comment="", + ) + + +def test_cancel_removes_every_pending_order_of_the_symbol( + trader: Trader, terminal: FakeTerminal +) -> None: + terminal.open_orders = [order(5, "EURUSD"), order(6, "XAUUSD"), order(7, "EURUSD", magic=1)] + result = trader.cancel_pending_orders("EURUSD") + assert isinstance(result, Ok) + assert terminal.sent == [CancelRequest(order=5), CancelRequest(order=7)] + + +def test_cancel_with_magic_filter(trader: Trader, terminal: FakeTerminal) -> None: + terminal.open_orders = [order(5, "EURUSD"), order(7, "EURUSD", magic=1)] + trader.cancel_pending_orders("EURUSD", magic=1) + assert terminal.sent == [CancelRequest(order=7)] + + +def test_queries_filter_by_magic(trader: Trader, terminal: FakeTerminal) -> None: + terminal.open_orders = [order(5, "EURUSD"), order(7, "EURUSD", magic=1)] + pending = trader.pending_orders(magic=1) + assert isinstance(pending, Ok) + assert [o.ticket for o in pending.value] == [7] + assert trader.positions("EURUSD") == Ok([]) + + +def test_shutdown_releases_the_terminal(trader: Trader, terminal: FakeTerminal) -> None: + trader.shutdown() + assert terminal.shut_down + + +def test_invalid_limit_order_never_reaches_the_terminal( + trader: Trader, terminal: FakeTerminal +) -> None: + result = trader.place_limit_order("EURUSD", "buy", 1000.0, 1.0) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_VOLUME + assert terminal.sent == [] From 727480c7bbbe1e50876b5b99340eb54dd8259319 Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 02:00:39 +0100 Subject: [PATCH 04/28] feat: add MetaTrader5 adapter, connect() and the 2.x Broker facade - MetaTrader5Terminal is the only module that knows MT5 request dicts and numeric order types. It imports the package lazily, so the library (and its unit tests) import on Linux where MetaTrader5 has no wheels. - Hidden symbols are selected into Market Watch automatically; a quote with a zero side is refused instead of trading at price 0. - None from positions_get/orders_get is split into "empty" vs "failed" via last_error(); 2.x treated a broken IPC link as "no positions". - connect() is the composition root and logs login@server only; 2.x logged the whole account_info (owner name, balance). - Broker keeps 2.x names, arguments and return shapes and emits a DeprecationWarning. It no longer loops forever and no longer presses Ctrl+E: that hotkey toggles (not enables) Algo Trading and is typed into whichever window has focus. - Logging uses stdlib `logging` without a NullHandler: with a NullHandler an unconfigured script would silently swallow every ERROR record, whereas stdlib's last-resort handler still prints them to stderr. - .gitattributes normalises line endings to LF. --- .gitattributes | 2 + README.md | 508 +++++++++--------- pyproject.toml | 6 +- src/PythonMetaTrader5/__init__.py | 47 ++ src/PythonMetaTrader5/adapters/__init__.py | 1 + .../adapters/mt5_terminal.py | 230 ++++++++ .../adapters/system_clock.py | 10 + src/PythonMetaTrader5/application/batch.py | 57 ++ src/PythonMetaTrader5/application/trader.py | 82 ++- src/PythonMetaTrader5/connection.py | 45 ++ src/PythonMetaTrader5/legacy/__init__.py | 1 + src/PythonMetaTrader5/legacy/broker.py | 273 ++++++++++ src/PythonMetaTrader5/legacy/views.py | 51 ++ tests/unit/fake_mt5.py | 129 +++++ tests/unit/test_close_positions.py | 3 +- tests/unit/test_connection.py | 68 +++ tests/unit/test_failure_paths.py | 3 +- tests/unit/test_legacy_broker.py | 157 ++++++ tests/unit/test_legacy_failures.py | 43 ++ tests/unit/test_mt5_adapter.py | 181 +++++++ tests/unit/test_pending_orders.py | 16 + 21 files changed, 1604 insertions(+), 309 deletions(-) create mode 100644 .gitattributes create mode 100644 src/PythonMetaTrader5/adapters/__init__.py create mode 100644 src/PythonMetaTrader5/adapters/mt5_terminal.py create mode 100644 src/PythonMetaTrader5/adapters/system_clock.py create mode 100644 src/PythonMetaTrader5/application/batch.py create mode 100644 src/PythonMetaTrader5/connection.py create mode 100644 src/PythonMetaTrader5/legacy/__init__.py create mode 100644 src/PythonMetaTrader5/legacy/broker.py create mode 100644 src/PythonMetaTrader5/legacy/views.py create mode 100644 tests/unit/fake_mt5.py create mode 100644 tests/unit/test_connection.py create mode 100644 tests/unit/test_legacy_broker.py create mode 100644 tests/unit/test_legacy_failures.py create mode 100644 tests/unit/test_mt5_adapter.py diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..cc23192 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,2 @@ +* text=auto eol=lf +*.bat text eol=crlf diff --git a/README.md b/README.md index ac89db3..f7c3c10 100644 --- a/README.md +++ b/README.md @@ -1,254 +1,254 @@ -# PythonMetaTrader5 [![PyPI Publish](https://github.com/Akinzou/MetaTrader5-Python/actions/workflows/python-publish.yml/badge.svg)](https://github.com/Akinzou/MetaTrader5-Python/actions/workflows/python-publish.yml) ![PyPI](https://img.shields.io/pypi/v/pythonmetatrader5) ![Python](https://img.shields.io/badge/python-3.6%2B-blue?logo=python&logoColor=white) ![License](https://img.shields.io/badge/license-CC_BY--NC_4.0-lightgrey.svg) [![PyPI Downloads](https://static.pepy.tech/badge/pythonmetatrader5)](https://pepy.tech/projects/pythonmetatrader5) - -[![Discord](https://img.shields.io/badge/Join_us_on-Discord-5865F2?logo=discord&logoColor=white&style=for-the-badge)](https://discord.gg/BARYa55KS8) - - -# MetaTrader5 Python Broker Helper - -Minimal, production‑ready helper around the official **MetaTrader5** Python package, -with a single market-entry function and clean handling of **SL/TP as absolute prices or offsets in POINTS**. -Includes utilities to read positions, close them, and manage pending orders. - -> Works with: `MetaTrader5`, `loguru`, `pyautogui` - ---- - -## Features - -* **Unified Execution Engine**: Single core function to open market positions (`OpenPosition(...)`). -* **Dynamic Risk Management**: SL/TP can be passed as **absolute prices** or flexible **offsets in POINTS**. -* **Input Sanitization**: Automatic price normalization to the correct instrument `digits`, preventing API rejection. -* **Robust Telemetry**: Consistent error handling with common MT5 `retcodes` mapped to readable messages. -* **Backward Compatibility**: Seamless wrappers for legacy integration (`Buy`, `Sell`, `BuySL`, `SellSL`). -* **State Helpers**: Efficient querying tools for current market exposure (`GetPositions`, `GetPosition`, `GetPositionsBySymbol`). -* **Lifecycle Management**: Complete control over active and pending trades (`Close`, `SellLimit`, `BuyLimit`, `CancelOrders`). - ---- - -## Installation - -```bash -pip install PythonMetaTrader5 -``` - -> Ensure your MetaTrader 5 terminal is running, logged in, and **Algo Trading** is enabled. - ---- - -## Quick Start - -```python -from PythonMetaTrader5 import Broker -import time - -# Login to your account -broker = Broker(96540048, "PASSWORD", "MetaQuotes-Demo") -time.sleep(1) # small grace period after login - -# Open BUY with SL/TP given as OFFSETS IN POINTS -r = broker.OpenPosition( - "EURUSD", "buy", 0.10, - sl=1000, sl_type="offset", # 1000 points (≈ 100 pips on 5-digit symbol) - tp=1500, tp_type="offset" -) - -# Read positions for a symbol -xau_positions = broker.GetPositionsBySymbol("XAUUSD", as_dict=True) - -# Close all positions on a symbol -broker.Close("EURUSD") - -# Cancel pending limit orders on a symbol -broker.CancelOrders("EURUSD") - -# Graceful shutdown -broker.Disconnect() -``` - ---- - -## SL/TP Semantics (Important) - -- `sl_type` / `tp_type`: - - `"absolute"` → you pass **absolute prices** (e.g., `1.23456`) - - `"offset"` → you pass **offsets in POINTS** (converted using `symbol_info(symbol).point`) - -- Offsets are applied from the **current tick price** (`ask` for BUY, `bid` for SELL): - - BUY : `SL = ask - |sl|*point`, `TP = ask + |tp|*point` - - SELL: `SL = bid + |sl|*point`, `TP = bid - |tp|*point` - -- All calculated prices (including absolute inputs) are normalized to the instrument `digits`. - -> If you get `Wrong SL (10016)`, check `symbol_info(symbol).stops_level` and multiply by `point` to know the minimal allowed distance. - ---- - -## API Reference - -### `class Broker` - -#### `__init__(self, log, password, server)` -Initialize MT5, attempt login, and print account info on success. - -- **log**: login number (int or str) -- **password**: account password (str) -- **server**: broker server name (str) - -#### `login(self, ToEffect=False) -> bool` -Retrying login loop. If `ToEffect` is `False`, returns immediately on failure. - ---- - -### Market Entry - -#### `OpenPosition(self, symbol, side, volume, *, sl=None, tp=None, price=None, comment=None, ticket=None, sl_type="absolute", tp_type="absolute")` -Open a market position. - -- **symbol**: e.g., `"EURUSD"` -- **side**: `"buy" | "sell" | "long" | "short"` -- **volume**: lot size (float) -- **sl**/**tp**: number (see `sl_type`/`tp_type`) -- **sl_type**/**tp_type**: `"absolute"` (prices) or `"offset"` (**POINTS**) -- **price**: optional direct price; if `None`, uses current tick (ask/bid) and retries on transient errors -- **comment**: optional MT5 order comment -- **ticket**: existing position id if needed (rarely used for market entry) - -**Returns**: result of `order_send` (MT5 `TradeResult`) - -**Examples**: -```python -# Absolute prices -broker.OpenPosition("XAUUSD", "sell", 0.10, sl=2400.0, tp=2380.0, sl_type="absolute", tp_type="absolute") - -# Offsets in POINTS -broker.OpenPosition("EURUSD", "buy", 0.10, sl=1000, tp=1500, sl_type="offset", tp_type="offset") -``` - ---- - -### Backward‑Compat Wrappers - -#### `Buy(self, symbol, volume, price=None, *, comment=None, ticket=None)` -Market BUY via `OpenPosition`. - -#### `Sell(self, symbol, volume, price=None, *, comment=None, ticket=None)` -Market SELL via `OpenPosition`. - -#### `BuySL(self, symbol, volume, sl, price=None, *, comment=None, ticket=None, sl_type="absolute")` -BUY with SL specified (absolute or offset in points). - -#### `SellSL(self, symbol, volume, sl, price=None, *, comment=None, ticket=None, sl_type="absolute")` -SELL with SL specified (absolute or offset in points). - ---- - -### Close & Pending Orders - -#### `Close(self, symbol, *, comment=None, ticket=None) -> bool` -Iteratively closes all positions for a **ticket** or for a **symbol** (same filtering semantics as `positions_get`). Returns `False` if nothing to close. - -#### `SellLimit(self, symbol, volume, stoplimit, price=None, comment=None, ticket=None)` -Create a SELL LIMIT order at `stoplimit`. If current `bid >= stoplimit`, executes a market SELL immediately for consistency. - -#### `BuyLimit(self, symbol, volume, stoplimit, price=None, comment=None, ticket=None)` -Create a BUY LIMIT order at `stoplimit`. If current `ask <= stoplimit`, executes a market BUY immediately. - -#### `CancelOrders(self, symbol)` -Cancel all BUY/SELL LIMIT pending orders on the given symbol. - -#### `Disconnect(self)` -Shutdown MT5 connection. - ---- - -### Positions Helpers - -#### `GetPositionsBySymbol(self, symbol: str, as_dict: bool = False) -> list` -Return all open positions for a symbol. If `as_dict=True`, returns a list of plain dictionaries (ready for JSON/GUI). - -#### `GetPositions(self, symbol=None, *, ticket=None, as_dict: bool = False) -> list` -Return positions with the same filter style as `Close()`: -- `ticket` provided → that single position -- else `symbol` provided → all for that symbol -- else → all positions - -#### `GetPosition(self, symbol=None, *, ticket=None, as_dict: bool = False)` -Return the first matching position (or `None`). Useful when at most one position is expected. - -**Example**: -```python -p = broker.GetPosition(symbol="XAUUSD", as_dict=True) -if p: - print("Ticket:", p["ticket"], "Type:", "BUY" if p["type"] == 0 else "SELL", "Profit:", p["profit"]) -``` - ---- - -## Error Handling & Retcodes - -- Known retcodes are mapped in `RetCodes`: - - `10027`: Enable Algo Trading in MetaTrader5 app - - `10018`: Market closed - - `10016`: Wrong SL - -- For `10027`, a `Ctrl+E` hotkey is issued via `pyautogui` to toggle Algo Trading. -- For `10016`, retries are **not** attempted (invalid SL/TP). - ---- - -## Advanced Examples - -```python -# 1) BUY with SL absolute price, TP as offset in points -broker.OpenPosition( - "US500", "buy", 1.0, - sl=5780.0, sl_type="absolute", - tp=200, tp_type="offset" -) - -# 2) SELL with both offsets in points -broker.OpenPosition( - "EURUSD", "sell", 0.2, - sl=800, tp=1200, - sl_type="offset", tp_type="offset" -) - -# 3) Get all positions as dicts and filter by profit -pos = broker.GetPositions(as_dict=True) -winners = [p for p in pos if p["profit"] > 0] - -# 4) Close by ticket -p = broker.GetPosition(symbol="XAUUSD") -if p: - broker.Close("XAUUSD", ticket=p.ticket) - -# 5) Pending orders -broker.BuyLimit("EURUSD", 0.10, stoplimit=1.10000) -broker.SellLimit("EURUSD", 0.10, stoplimit=1.12000) -broker.CancelOrders("EURUSD") -``` - ---- - -## Notes - -- Ensure the symbol is visible/active in MT5 Market Watch. -- Check `stops_level`/`freeze_level` on your broker if SL/TP are rejected: - ```python - info = symbol_info("EURUSD") - print(info.point, info.digits, info.stops_level, info.freeze_level, info.volume_min, info.volume_step) - ``` -- `volume` must respect broker `volume_min`/`volume_step`. - ---- - -## License - -CC-BY-NC 4.0 - - - - - - - +# PythonMetaTrader5 [![PyPI Publish](https://github.com/Akinzou/MetaTrader5-Python/actions/workflows/python-publish.yml/badge.svg)](https://github.com/Akinzou/MetaTrader5-Python/actions/workflows/python-publish.yml) ![PyPI](https://img.shields.io/pypi/v/pythonmetatrader5) ![Python](https://img.shields.io/badge/python-3.6%2B-blue?logo=python&logoColor=white) ![License](https://img.shields.io/badge/license-CC_BY--NC_4.0-lightgrey.svg) [![PyPI Downloads](https://static.pepy.tech/badge/pythonmetatrader5)](https://pepy.tech/projects/pythonmetatrader5) + +[![Discord](https://img.shields.io/badge/Join_us_on-Discord-5865F2?logo=discord&logoColor=white&style=for-the-badge)](https://discord.gg/BARYa55KS8) + + +# MetaTrader5 Python Broker Helper + +Minimal, production‑ready helper around the official **MetaTrader5** Python package, +with a single market-entry function and clean handling of **SL/TP as absolute prices or offsets in POINTS**. +Includes utilities to read positions, close them, and manage pending orders. + +> Works with: `MetaTrader5`, `loguru`, `pyautogui` + +--- + +## Features + +* **Unified Execution Engine**: Single core function to open market positions (`OpenPosition(...)`). +* **Dynamic Risk Management**: SL/TP can be passed as **absolute prices** or flexible **offsets in POINTS**. +* **Input Sanitization**: Automatic price normalization to the correct instrument `digits`, preventing API rejection. +* **Robust Telemetry**: Consistent error handling with common MT5 `retcodes` mapped to readable messages. +* **Backward Compatibility**: Seamless wrappers for legacy integration (`Buy`, `Sell`, `BuySL`, `SellSL`). +* **State Helpers**: Efficient querying tools for current market exposure (`GetPositions`, `GetPosition`, `GetPositionsBySymbol`). +* **Lifecycle Management**: Complete control over active and pending trades (`Close`, `SellLimit`, `BuyLimit`, `CancelOrders`). + +--- + +## Installation + +```bash +pip install PythonMetaTrader5 +``` + +> Ensure your MetaTrader 5 terminal is running, logged in, and **Algo Trading** is enabled. + +--- + +## Quick Start + +```python +from PythonMetaTrader5 import Broker +import time + +# Login to your account +broker = Broker(96540048, "PASSWORD", "MetaQuotes-Demo") +time.sleep(1) # small grace period after login + +# Open BUY with SL/TP given as OFFSETS IN POINTS +r = broker.OpenPosition( + "EURUSD", "buy", 0.10, + sl=1000, sl_type="offset", # 1000 points (≈ 100 pips on 5-digit symbol) + tp=1500, tp_type="offset" +) + +# Read positions for a symbol +xau_positions = broker.GetPositionsBySymbol("XAUUSD", as_dict=True) + +# Close all positions on a symbol +broker.Close("EURUSD") + +# Cancel pending limit orders on a symbol +broker.CancelOrders("EURUSD") + +# Graceful shutdown +broker.Disconnect() +``` + +--- + +## SL/TP Semantics (Important) + +- `sl_type` / `tp_type`: + - `"absolute"` → you pass **absolute prices** (e.g., `1.23456`) + - `"offset"` → you pass **offsets in POINTS** (converted using `symbol_info(symbol).point`) + +- Offsets are applied from the **current tick price** (`ask` for BUY, `bid` for SELL): + - BUY : `SL = ask - |sl|*point`, `TP = ask + |tp|*point` + - SELL: `SL = bid + |sl|*point`, `TP = bid - |tp|*point` + +- All calculated prices (including absolute inputs) are normalized to the instrument `digits`. + +> If you get `Wrong SL (10016)`, check `symbol_info(symbol).stops_level` and multiply by `point` to know the minimal allowed distance. + +--- + +## API Reference + +### `class Broker` + +#### `__init__(self, log, password, server)` +Initialize MT5, attempt login, and print account info on success. + +- **log**: login number (int or str) +- **password**: account password (str) +- **server**: broker server name (str) + +#### `login(self, ToEffect=False) -> bool` +Retrying login loop. If `ToEffect` is `False`, returns immediately on failure. + +--- + +### Market Entry + +#### `OpenPosition(self, symbol, side, volume, *, sl=None, tp=None, price=None, comment=None, ticket=None, sl_type="absolute", tp_type="absolute")` +Open a market position. + +- **symbol**: e.g., `"EURUSD"` +- **side**: `"buy" | "sell" | "long" | "short"` +- **volume**: lot size (float) +- **sl**/**tp**: number (see `sl_type`/`tp_type`) +- **sl_type**/**tp_type**: `"absolute"` (prices) or `"offset"` (**POINTS**) +- **price**: optional direct price; if `None`, uses current tick (ask/bid) and retries on transient errors +- **comment**: optional MT5 order comment +- **ticket**: existing position id if needed (rarely used for market entry) + +**Returns**: result of `order_send` (MT5 `TradeResult`) + +**Examples**: +```python +# Absolute prices +broker.OpenPosition("XAUUSD", "sell", 0.10, sl=2400.0, tp=2380.0, sl_type="absolute", tp_type="absolute") + +# Offsets in POINTS +broker.OpenPosition("EURUSD", "buy", 0.10, sl=1000, tp=1500, sl_type="offset", tp_type="offset") +``` + +--- + +### Backward‑Compat Wrappers + +#### `Buy(self, symbol, volume, price=None, *, comment=None, ticket=None)` +Market BUY via `OpenPosition`. + +#### `Sell(self, symbol, volume, price=None, *, comment=None, ticket=None)` +Market SELL via `OpenPosition`. + +#### `BuySL(self, symbol, volume, sl, price=None, *, comment=None, ticket=None, sl_type="absolute")` +BUY with SL specified (absolute or offset in points). + +#### `SellSL(self, symbol, volume, sl, price=None, *, comment=None, ticket=None, sl_type="absolute")` +SELL with SL specified (absolute or offset in points). + +--- + +### Close & Pending Orders + +#### `Close(self, symbol, *, comment=None, ticket=None) -> bool` +Iteratively closes all positions for a **ticket** or for a **symbol** (same filtering semantics as `positions_get`). Returns `False` if nothing to close. + +#### `SellLimit(self, symbol, volume, stoplimit, price=None, comment=None, ticket=None)` +Create a SELL LIMIT order at `stoplimit`. If current `bid >= stoplimit`, executes a market SELL immediately for consistency. + +#### `BuyLimit(self, symbol, volume, stoplimit, price=None, comment=None, ticket=None)` +Create a BUY LIMIT order at `stoplimit`. If current `ask <= stoplimit`, executes a market BUY immediately. + +#### `CancelOrders(self, symbol)` +Cancel all BUY/SELL LIMIT pending orders on the given symbol. + +#### `Disconnect(self)` +Shutdown MT5 connection. + +--- + +### Positions Helpers + +#### `GetPositionsBySymbol(self, symbol: str, as_dict: bool = False) -> list` +Return all open positions for a symbol. If `as_dict=True`, returns a list of plain dictionaries (ready for JSON/GUI). + +#### `GetPositions(self, symbol=None, *, ticket=None, as_dict: bool = False) -> list` +Return positions with the same filter style as `Close()`: +- `ticket` provided → that single position +- else `symbol` provided → all for that symbol +- else → all positions + +#### `GetPosition(self, symbol=None, *, ticket=None, as_dict: bool = False)` +Return the first matching position (or `None`). Useful when at most one position is expected. + +**Example**: +```python +p = broker.GetPosition(symbol="XAUUSD", as_dict=True) +if p: + print("Ticket:", p["ticket"], "Type:", "BUY" if p["type"] == 0 else "SELL", "Profit:", p["profit"]) +``` + +--- + +## Error Handling & Retcodes + +- Known retcodes are mapped in `RetCodes`: + - `10027`: Enable Algo Trading in MetaTrader5 app + - `10018`: Market closed + - `10016`: Wrong SL + +- For `10027`, a `Ctrl+E` hotkey is issued via `pyautogui` to toggle Algo Trading. +- For `10016`, retries are **not** attempted (invalid SL/TP). + +--- + +## Advanced Examples + +```python +# 1) BUY with SL absolute price, TP as offset in points +broker.OpenPosition( + "US500", "buy", 1.0, + sl=5780.0, sl_type="absolute", + tp=200, tp_type="offset" +) + +# 2) SELL with both offsets in points +broker.OpenPosition( + "EURUSD", "sell", 0.2, + sl=800, tp=1200, + sl_type="offset", tp_type="offset" +) + +# 3) Get all positions as dicts and filter by profit +pos = broker.GetPositions(as_dict=True) +winners = [p for p in pos if p["profit"] > 0] + +# 4) Close by ticket +p = broker.GetPosition(symbol="XAUUSD") +if p: + broker.Close("XAUUSD", ticket=p.ticket) + +# 5) Pending orders +broker.BuyLimit("EURUSD", 0.10, stoplimit=1.10000) +broker.SellLimit("EURUSD", 0.10, stoplimit=1.12000) +broker.CancelOrders("EURUSD") +``` + +--- + +## Notes + +- Ensure the symbol is visible/active in MT5 Market Watch. +- Check `stops_level`/`freeze_level` on your broker if SL/TP are rejected: + ```python + info = symbol_info("EURUSD") + print(info.point, info.digits, info.stops_level, info.freeze_level, info.volume_min, info.volume_step) + ``` +- `volume` must respect broker `volume_min`/`volume_step`. + +--- + +## License + +CC-BY-NC 4.0 + + + + + + + diff --git a/pyproject.toml b/pyproject.toml index f5ee621..ff65d72 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -73,8 +73,10 @@ ignore = ["PLR0913", "N999"] [tool.ruff.lint.per-file-ignores] # The 2.x public method names (Buy, GetPositions, ToEffect...) are the compatibility contract. -"src/PythonMetaTrader5/legacy/*.py" = ["N802", "N803", "N815"] -"tests/**/*.py" = ["S101", "PLR2004"] +# PLR0917: BuyLimit/SellLimit accepted price, comment and ticket positionally in 2.x. +"src/PythonMetaTrader5/legacy/*.py" = ["N802", "N803", "N815", "PLR0917"] +# S106: tests use throwaway fake credentials. +"tests/**/*.py" = ["S101", "S106", "PLR2004"] [tool.mypy] strict = true diff --git a/src/PythonMetaTrader5/__init__.py b/src/PythonMetaTrader5/__init__.py index e69de29..6923e84 100644 --- a/src/PythonMetaTrader5/__init__.py +++ b/src/PythonMetaTrader5/__init__.py @@ -0,0 +1,47 @@ +"""PythonMetaTrader5: a safe, typed trading layer over the MetaTrader5 package. + +from PythonMetaTrader5 import connect, Stop, Ok, Err + +match connect(12345678, "password", "MetaQuotes-Demo", magic=1001): + case Ok(trader): + trader.open_position("EURUSD", "buy", 0.1, sl=Stop.points(1000)) + case Err(error): + print(error) +""" + +from PythonMetaTrader5.application.batch import BatchFailure +from PythonMetaTrader5.application.execution import RetryPolicy +from PythonMetaTrader5.application.trader import Trader +from PythonMetaTrader5.connection import connect +from PythonMetaTrader5.domain.errors import ErrorKind, TradeError +from PythonMetaTrader5.domain.market import ( + PendingKind, + PendingOrder, + Position, + Tick, + TradeReceipt, +) +from PythonMetaTrader5.domain.orders import Side +from PythonMetaTrader5.domain.stops import Stop +from PythonMetaTrader5.legacy.broker import Broker +from PythonMetaTrader5.result import Err, Ok, Result + +__all__ = [ + "BatchFailure", + "Broker", + "Err", + "ErrorKind", + "Ok", + "PendingKind", + "PendingOrder", + "Position", + "Result", + "RetryPolicy", + "Side", + "Stop", + "Tick", + "TradeError", + "TradeReceipt", + "Trader", + "connect", +] diff --git a/src/PythonMetaTrader5/adapters/__init__.py b/src/PythonMetaTrader5/adapters/__init__.py new file mode 100644 index 0000000..8373d81 --- /dev/null +++ b/src/PythonMetaTrader5/adapters/__init__.py @@ -0,0 +1 @@ +"""Implementations of the application ports for the real world.""" diff --git a/src/PythonMetaTrader5/adapters/mt5_terminal.py b/src/PythonMetaTrader5/adapters/mt5_terminal.py new file mode 100644 index 0000000..fab7a81 --- /dev/null +++ b/src/PythonMetaTrader5/adapters/mt5_terminal.py @@ -0,0 +1,230 @@ +"""Terminal port implemented with the official `MetaTrader5` package. + +This is the only module that knows MT5's request dictionaries, numeric order +types and the shape of its result objects. +""" + +from __future__ import annotations + +import importlib +from typing import Any + +from PythonMetaTrader5.application.ports import Credentials +from PythonMetaTrader5.domain.errors import ErrorKind, TradeError +from PythonMetaTrader5.domain.market import ( + PendingKind, + PendingOrder, + Position, + Tick, + TradeReceipt, +) +from PythonMetaTrader5.domain.orders import Side +from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest +from PythonMetaTrader5.domain.symbol import Filling, SymbolSpec +from PythonMetaTrader5.result import Err, Ok, Result + +# MT5 reports "nothing found" and "call failed" both as None; only last_error() +# tells them apart. 1 is RES_S_OK. +_RES_S_OK = 1 + + +class MetaTrader5Terminal: + def __init__(self, mt5: Any) -> None: + # `Any`: the MetaTrader5 package ships no type information. + self._mt5 = mt5 + self._order_types = _order_type_table(mt5) + self._pending_by_type = { + code: (side, kind) + for (side, kind), code in self._order_types.items() + if kind is not None + } + self._fillings = { + Filling.FOK: mt5.ORDER_FILLING_FOK, + Filling.IOC: mt5.ORDER_FILLING_IOC, + Filling.RETURN: mt5.ORDER_FILLING_RETURN, + } + + @classmethod + def load(cls) -> Result[MetaTrader5Terminal, TradeError]: + try: + module = importlib.import_module("MetaTrader5") + except ImportError: + return Err( + TradeError( + ErrorKind.CONNECTION_FAILED, + "the MetaTrader5 package is not installed (it is available on Windows only)", + ) + ) + return Ok(cls(module)) + + def connect(self, credentials: Credentials) -> Result[None, TradeError]: + args = (credentials.path,) if credentials.path else () + if self._mt5.initialize( + *args, + login=credentials.login, + password=credentials.password, + server=credentials.server, + timeout=credentials.timeout_ms, + ): + return Ok(None) + return Err( + TradeError( + ErrorKind.CONNECTION_FAILED, + f"login {credentials.login}@{credentials.server} failed: {self._last_error()}", + ) + ) + + def shutdown(self) -> None: + self._mt5.shutdown() + + def symbol(self, name: str) -> Result[SymbolSpec, TradeError]: + info = self._mt5.symbol_info(name) + if info is None: + return Err(TradeError(ErrorKind.SYMBOL_NOT_FOUND, f"unknown symbol {name!r}")) + if not info.visible: + # Hidden symbols have no quotes; 2.x left users to fix Market Watch by hand. + self._mt5.symbol_select(name, True) + return Ok( + SymbolSpec( + name=info.name, + digits=int(info.digits), + point=float(info.point), + tick_size=float(info.trade_tick_size), + volume_min=float(info.volume_min), + volume_max=float(info.volume_max), + volume_step=float(info.volume_step), + filling_flags=int(info.filling_mode), + stops_level=int(info.trade_stops_level), + ) + ) + + def tick(self, name: str) -> Result[Tick, TradeError]: + tick = self._mt5.symbol_info_tick(name) + # A zero side means no quote yet; trading at price 0 must never be attempted. + if tick is None or tick.bid <= 0 or tick.ask <= 0: + return Err(TradeError(ErrorKind.NO_PRICE, f"no quote for {name!r}")) + return Ok(Tick(bid=float(tick.bid), ask=float(tick.ask))) + + def send(self, request: OrderRequest | CancelRequest) -> Result[TradeReceipt, TradeError]: + payload = self._payload(request) + result = self._mt5.order_send(payload) + if result is None: + return Err( + TradeError(ErrorKind.TERMINAL_ERROR, f"order_send failed: {self._last_error()}") + ) + return Ok( + TradeReceipt( + retcode=int(result.retcode), + deal=int(result.deal), + order=int(result.order), + volume=float(result.volume), + price=float(result.price), + bid=float(result.bid), + ask=float(result.ask), + comment=str(result.comment), + request_id=int(result.request_id), + ) + ) + + def positions( + self, *, symbol: str | None = None, ticket: int | None = None + ) -> Result[list[Position], TradeError]: + query = {"ticket": ticket} if ticket is not None else {"symbol": symbol} if symbol else {} + raw = self._listing(self._mt5.positions_get(**query), "positions_get") + if isinstance(raw, Err): + return raw + return Ok([self._position(p) for p in raw.value]) + + def pending_orders( + self, *, symbol: str | None = None + ) -> Result[list[PendingOrder], TradeError]: + query = {"symbol": symbol} if symbol else {} + raw = self._listing(self._mt5.orders_get(**query), "orders_get") + if isinstance(raw, Err): + return raw + orders = [] + for o in raw.value: + key = self._pending_by_type.get(int(o.type)) + # Market orders still being processed and close-by orders are not resting orders. + if key is None: + continue + side, kind = key + orders.append( + PendingOrder( + ticket=int(o.ticket), + symbol=str(o.symbol), + side=side, + kind=kind, + volume=float(o.volume_current), + price=float(o.price_open), + magic=int(o.magic), + comment=str(o.comment), + ) + ) + return Ok(orders) + + # ------------------------------------------------------------------ helpers + + def _payload(self, request: OrderRequest | CancelRequest) -> dict[str, Any]: + mt5 = self._mt5 + if isinstance(request, CancelRequest): + return {"action": mt5.TRADE_ACTION_REMOVE, "order": request.order} + payload: dict[str, Any] = { + "action": mt5.TRADE_ACTION_DEAL + if request.pending is None + else mt5.TRADE_ACTION_PENDING, + "symbol": request.symbol, + "volume": request.volume, + "type": self._order_types[(request.side, request.pending)], + "price": request.price, + "deviation": request.deviation, + "magic": request.magic, + "comment": request.comment, + "type_filling": self._fillings[request.filling], + "type_time": mt5.ORDER_TIME_GTC, + } + optional = {"sl": request.sl, "tp": request.tp, "position": request.position} + payload.update({key: value for key, value in optional.items() if value is not None}) + return payload + + def _position(self, p: Any) -> Position: + return Position( + ticket=int(p.ticket), + symbol=str(p.symbol), + side=Side.BUY if p.type == self._mt5.POSITION_TYPE_BUY else Side.SELL, + volume=float(p.volume), + price_open=float(p.price_open), + # MT5 encodes "no stop" as 0.0, which is also a (useless) price. + sl=float(p.sl) or None, + tp=float(p.tp) or None, + price_current=float(p.price_current), + profit=float(p.profit), + time=int(p.time), + magic=int(p.magic), + comment=str(p.comment), + ) + + def _listing(self, raw: Any, call: str) -> Result[tuple[Any, ...], TradeError]: + if raw is not None: + return Ok(tuple(raw)) + code, _ = self._mt5.last_error() + if code == _RES_S_OK: + return Ok(()) + return Err(TradeError(ErrorKind.TERMINAL_ERROR, f"{call} failed: {self._last_error()}")) + + def _last_error(self) -> str: + code, message = self._mt5.last_error() + return f"[{code}] {message}" + + +def _order_type_table(mt5: Any) -> dict[tuple[Side, PendingKind | None], int]: + return { + (Side.BUY, None): mt5.ORDER_TYPE_BUY, + (Side.SELL, None): mt5.ORDER_TYPE_SELL, + (Side.BUY, PendingKind.LIMIT): mt5.ORDER_TYPE_BUY_LIMIT, + (Side.SELL, PendingKind.LIMIT): mt5.ORDER_TYPE_SELL_LIMIT, + (Side.BUY, PendingKind.STOP): mt5.ORDER_TYPE_BUY_STOP, + (Side.SELL, PendingKind.STOP): mt5.ORDER_TYPE_SELL_STOP, + (Side.BUY, PendingKind.STOP_LIMIT): mt5.ORDER_TYPE_BUY_STOP_LIMIT, + (Side.SELL, PendingKind.STOP_LIMIT): mt5.ORDER_TYPE_SELL_STOP_LIMIT, + } diff --git a/src/PythonMetaTrader5/adapters/system_clock.py b/src/PythonMetaTrader5/adapters/system_clock.py new file mode 100644 index 0000000..b56d19c --- /dev/null +++ b/src/PythonMetaTrader5/adapters/system_clock.py @@ -0,0 +1,10 @@ +"""Wall-clock adapter for the Clock port.""" + +from __future__ import annotations + +import time + + +class SystemClock: + def sleep(self, seconds: float) -> None: + time.sleep(seconds) diff --git a/src/PythonMetaTrader5/application/batch.py b/src/PythonMetaTrader5/application/batch.py new file mode 100644 index 0000000..0fde847 --- /dev/null +++ b/src/PythonMetaTrader5/application/batch.py @@ -0,0 +1,57 @@ +"""Applying one trade action to many positions/orders and reporting per item.""" + +from __future__ import annotations + +from collections.abc import Callable, Iterable +from dataclasses import dataclass, replace +from typing import Protocol, TypeVar + +from PythonMetaTrader5.domain.errors import TradeError +from PythonMetaTrader5.domain.market import TradeReceipt +from PythonMetaTrader5.result import Err, Ok, Result + + +class _Ticketed(Protocol): + @property + def ticket(self) -> int: ... + + @property + def magic(self) -> int: ... + + +_T = TypeVar("_T", bound=_Ticketed) + + +@dataclass(frozen=True, slots=True) +class BatchFailure: + """Some items of a batch (close all / cancel all) failed; others may have succeeded.""" + + succeeded: tuple[TradeReceipt, ...] + errors: tuple[TradeError, ...] + + def __str__(self) -> str: + return f"{len(self.errors)} failed, {len(self.succeeded)} succeeded: " + "; ".join( + str(e) for e in self.errors + ) + + +def run_batch( + items: Iterable[_T], action: Callable[[_T], Result[TradeReceipt, TradeError]] +) -> Result[list[TradeReceipt], BatchFailure]: + # Every item is attempted even after a failure: stopping at the first error + # would leave the remaining positions open while reporting only one problem. + succeeded: list[TradeReceipt] = [] + errors: list[TradeError] = [] + for item in items: + match action(item): + case Ok(receipt): + succeeded.append(receipt) + case Err(error): + errors.append(replace(error, ticket=item.ticket)) + if errors: + return Err(BatchFailure(tuple(succeeded), tuple(errors))) + return Ok(succeeded) + + +def with_magic(items: list[_T], magic: int | None) -> list[_T]: + return items if magic is None else [item for item in items if item.magic == magic] diff --git a/src/PythonMetaTrader5/application/trader.py b/src/PythonMetaTrader5/application/trader.py index cdfc5a4..a699065 100644 --- a/src/PythonMetaTrader5/application/trader.py +++ b/src/PythonMetaTrader5/application/trader.py @@ -2,10 +2,10 @@ from __future__ import annotations -from collections.abc import Callable, Iterable from dataclasses import dataclass, replace -from typing import Protocol, TypeVar +from types import TracebackType +from PythonMetaTrader5.application.batch import BatchFailure, run_batch, with_magic from PythonMetaTrader5.application.execution import RetryPolicy, execute from PythonMetaTrader5.application.ports import Clock, Terminal from PythonMetaTrader5.domain.errors import TradeError @@ -19,27 +19,6 @@ StopInput = Stop | float | None -class _HasMagic(Protocol): - @property - def magic(self) -> int: ... - - -_M = TypeVar("_M", bound=_HasMagic) - - -@dataclass(frozen=True, slots=True) -class BatchFailure: - """Some items of a batch (close all / cancel all) failed; others may have succeeded.""" - - succeeded: tuple[TradeReceipt, ...] - errors: tuple[TradeError, ...] - - def __str__(self) -> str: - return f"{len(self.errors)} failed, {len(self.succeeded)} succeeded: " + "; ".join( - str(e) for e in self.errors - ) - - @dataclass(frozen=True, slots=True) class _Entry: """Validated parameters shared by market and pending entries.""" @@ -152,15 +131,19 @@ def close_positions( listed = self.positions(None if ticket is not None else symbol, ticket=ticket, magic=magic) if isinstance(listed, Err): return Err(BatchFailure((), (listed.error,))) - return self._batch(listed.value, lambda p: self._close_one(p, text.value)) + return run_batch(listed.value, lambda p: self._close_one(p, text.value)) def cancel_pending_orders( - self, symbol: str | None = None, *, magic: int | None = None + self, + symbol: str | None = None, + *, + magic: int | None = None, + kind: PendingKind | None = None, ) -> Result[list[TradeReceipt], BatchFailure]: - listed = self.pending_orders(symbol, magic=magic) + listed = self.pending_orders(symbol, magic=magic, kind=kind) if isinstance(listed, Err): return Err(BatchFailure((), (listed.error,))) - return self._batch(listed.value, self._cancel_one) + return run_batch(listed.value, self._cancel_one) # ----------------------------------------------------------------- queries @@ -168,17 +151,35 @@ def positions( self, symbol: str | None = None, *, ticket: int | None = None, magic: int | None = None ) -> Result[list[Position], TradeError]: listed = self._terminal.positions(symbol=symbol, ticket=ticket) - return listed if isinstance(listed, Err) else Ok(_with_magic(listed.value, magic)) + return listed if isinstance(listed, Err) else Ok(with_magic(listed.value, magic)) def pending_orders( - self, symbol: str | None = None, *, magic: int | None = None + self, + symbol: str | None = None, + *, + magic: int | None = None, + kind: PendingKind | None = None, ) -> Result[list[PendingOrder], TradeError]: listed = self._terminal.pending_orders(symbol=symbol) - return listed if isinstance(listed, Err) else Ok(_with_magic(listed.value, magic)) + if isinstance(listed, Err): + return listed + orders = with_magic(listed.value, magic) + return Ok(orders if kind is None else [o for o in orders if o.kind is kind]) def shutdown(self) -> None: self._terminal.shutdown() + def __enter__(self) -> Trader: + return self + + def __exit__( + self, + exc_type: type[BaseException] | None, + exc: BaseException | None, + tb: TracebackType | None, + ) -> None: + self.shutdown() + # ----------------------------------------------------------------- helpers def _validate_entry( @@ -253,29 +254,8 @@ def _cancel_one(self, order: PendingOrder) -> Result[TradeReceipt, TradeError]: request = CancelRequest(order=order.ticket) return execute(self._terminal, self._clock, lambda: Ok(request), self._retry) - def _batch( - self, - items: Iterable[Position] | Iterable[PendingOrder], - action: Callable[..., Result[TradeReceipt, TradeError]], - ) -> Result[list[TradeReceipt], BatchFailure]: - succeeded: list[TradeReceipt] = [] - errors: list[TradeError] = [] - for item in items: - match action(item): - case Ok(receipt): - succeeded.append(receipt) - case Err(error): - errors.append(replace(error, ticket=item.ticket)) - if errors: - return Err(BatchFailure(tuple(succeeded), tuple(errors))) - return Ok(succeeded) - def _as_stop(value: StopInput) -> Stop | None: if value is None or isinstance(value, Stop): return value return Stop.at_price(value) - - -def _with_magic(items: list[_M], magic: int | None) -> list[_M]: - return items if magic is None else [item for item in items if item.magic == magic] diff --git a/src/PythonMetaTrader5/connection.py b/src/PythonMetaTrader5/connection.py new file mode 100644 index 0000000..ef1ca46 --- /dev/null +++ b/src/PythonMetaTrader5/connection.py @@ -0,0 +1,45 @@ +"""Composition root: wires the real adapters into a Trader.""" + +from __future__ import annotations + +import logging + +from PythonMetaTrader5.adapters.mt5_terminal import MetaTrader5Terminal +from PythonMetaTrader5.adapters.system_clock import SystemClock +from PythonMetaTrader5.application.execution import RetryPolicy +from PythonMetaTrader5.application.ports import Credentials +from PythonMetaTrader5.application.trader import Trader +from PythonMetaTrader5.domain.errors import ErrorKind, TradeError +from PythonMetaTrader5.result import Err, Ok, Result + +log = logging.getLogger("PythonMetaTrader5") + + +def connect( + login: int | str, + password: str, + server: str, + *, + path: str | None = None, + timeout_ms: int = 60_000, + magic: int = 0, + deviation: int = 10, + retry: RetryPolicy | None = None, +) -> Result[Trader, TradeError]: + """Start (or attach to) the MT5 terminal, log in, and return a ready Trader.""" + try: + account = int(login) + except ValueError: + return Err(TradeError(ErrorKind.INVALID_ARGUMENT, f"login must be numeric, got {login!r}")) + loaded = MetaTrader5Terminal.load() + if isinstance(loaded, Err): + return loaded + terminal = loaded.value + credentials = Credentials(account, str(password), str(server), path, timeout_ms) + connected = terminal.connect(credentials) + if isinstance(connected, Err): + return connected + # Login and server only: account_info() also carries the owner's name and + # balance, which do not belong in application logs. + log.info("connected to %s as %s", server, account) + return Ok(Trader(terminal, SystemClock(), magic=magic, deviation=deviation, retry=retry)) diff --git a/src/PythonMetaTrader5/legacy/__init__.py b/src/PythonMetaTrader5/legacy/__init__.py new file mode 100644 index 0000000..7a1e60f --- /dev/null +++ b/src/PythonMetaTrader5/legacy/__init__.py @@ -0,0 +1 @@ +"""Deprecated 2.x API kept so existing scripts run unchanged on 3.x.""" diff --git a/src/PythonMetaTrader5/legacy/broker.py b/src/PythonMetaTrader5/legacy/broker.py new file mode 100644 index 0000000..1f306b4 --- /dev/null +++ b/src/PythonMetaTrader5/legacy/broker.py @@ -0,0 +1,273 @@ +"""2.x `Broker` facade over the 3.x Trader. + +Names, arguments and return shapes follow 2.x so old scripts keep running. The +behaviour that made 2.x dangerous is NOT preserved: no endless retry loops and +no Ctrl+E keystrokes into whichever window has focus. See MIGRATION.md. +""" + +from __future__ import annotations + +import logging +import warnings +from typing import Any, ClassVar + +from PythonMetaTrader5.adapters.mt5_terminal import MetaTrader5Terminal +from PythonMetaTrader5.adapters.system_clock import SystemClock +from PythonMetaTrader5.application.ports import Clock, Credentials, Terminal +from PythonMetaTrader5.application.trader import Trader +from PythonMetaTrader5.domain.errors import TradeError +from PythonMetaTrader5.domain.market import PendingKind, TradeReceipt +from PythonMetaTrader5.domain.orders import Side +from PythonMetaTrader5.domain.stops import Stop +from PythonMetaTrader5.legacy import views +from PythonMetaTrader5.result import Err, Ok, Result + +log = logging.getLogger("PythonMetaTrader5.legacy") + +_RELOGIN_DELAY_SECONDS = 1.0 + + +class Broker: + RetCodes: ClassVar[dict[int, str]] = { + 10027: "Enable Algo Trading in MetaTrader5 app", + 10018: "Market closed", + 10016: "Wrong SL", + } + + def __init__( + self, + log: int | str, + password: Any, + server: Any, + *, + terminal: Terminal | None = None, + clock: Clock | None = None, + ) -> None: + warnings.warn( + "Broker is deprecated; use PythonMetaTrader5.connect() (see MIGRATION.md)", + DeprecationWarning, + stacklevel=2, + ) + self.log = log + self.server = str(server) + self._credentials = Credentials(int(log), str(password), self.server) + self._clock = clock or SystemClock() + self._terminal = terminal or _load_terminal() + self._trader = Trader(self._terminal, self._clock) if self._terminal else None + self._connected = self.login() + + def login(self, ToEffect: bool = False) -> bool: + """Log in once, or keep trying every second until it works when ``ToEffect``.""" + if self._terminal is None: + return False + while True: + result = self._terminal.connect(self._credentials) + if isinstance(result, Ok): + log.info("%s: logged in to %s", self.log, self.server) + self._connected = True + return True + log.error("%s: %s", self.log, result.error) + if not ToEffect: + return False + self._clock.sleep(_RELOGIN_DELAY_SECONDS) + + # ---------------------------------------------------------------- queries + + def GetPositionsBySymbol(self, symbol: str, as_dict: bool = False) -> list[Any]: + return self.GetPositions(symbol, as_dict=as_dict) + + def GetPositions( + self, symbol: str | None = None, *, ticket: int | None = None, as_dict: bool = False + ) -> list[Any]: + trader = self._ready() + if trader is None: + return [] + listed = trader.positions(symbol, ticket=ticket) + if isinstance(listed, Err): + log.error("%s: %s", self.log, listed.error) + return [] + convert = views.as_dict if as_dict else views.as_object + return [convert(p) for p in listed.value] + + def GetPosition( + self, symbol: str | None = None, *, ticket: int | None = None, as_dict: bool = False + ) -> Any: + found = self.GetPositions(symbol, ticket=ticket, as_dict=as_dict) + return found[0] if found else None + + # ---------------------------------------------------------------- entries + + def OpenPosition( + self, + symbol: str, + side: str, + volume: float, + *, + sl: float | None = None, + tp: float | None = None, + price: float | None = None, + comment: str | None = None, + ticket: int | None = None, + sl_type: str = "absolute", + tp_type: str = "absolute", + ) -> TradeReceipt | None: + trader = self._ready() + if trader is None or not _no_ticket(ticket): + return None + stops = _legacy_stop(sl, sl_type), _legacy_stop(tp, tp_type) + if any(isinstance(stop, Err) for stop in stops): + return None + stop_loss, take_profit = (s.value for s in stops if isinstance(s, Ok)) + result = trader.open_position( + symbol, side, volume, sl=stop_loss, tp=take_profit, price=price, comment=comment + ) + return self._receipt(result, f"{side} {symbol}") + + def Buy(self, symbol: str, volume: float, price: float | None = None, **kw: Any) -> Any: + return self.OpenPosition(symbol, "buy", volume, price=price, **kw) + + def BuySL( + self, symbol: str, volume: float, sl: float, price: float | None = None, **kw: Any + ) -> Any: + return self.OpenPosition(symbol, "buy", volume, sl=sl, price=price, **kw) + + def Sell(self, symbol: str, volume: float, price: float | None = None, **kw: Any) -> Any: + return self.OpenPosition(symbol, "sell", volume, price=price, **kw) + + def SellSL( + self, symbol: str, volume: float, sl: float, price: float | None = None, **kw: Any + ) -> Any: + return self.OpenPosition(symbol, "sell", volume, sl=sl, price=price, **kw) + + def BuyLimit( + self, + symbol: str, + volume: float, + stoplimit: float, + price: float | None = None, + comment: str | None = None, + ticket: int | None = None, + ) -> TradeReceipt | None: + return self._limit( + Side.BUY, symbol, volume, stoplimit, price=price, comment=comment, ticket=ticket + ) + + def SellLimit( + self, + symbol: str, + volume: float, + stoplimit: float, + price: float | None = None, + comment: str | None = None, + ticket: int | None = None, + ) -> TradeReceipt | None: + return self._limit( + Side.SELL, symbol, volume, stoplimit, price=price, comment=comment, ticket=ticket + ) + + # ------------------------------------------------------------------ exits + + def Close( + self, symbol: str | None, *, comment: str | None = None, ticket: int | None = None + ) -> bool: + """True when at least one position closed and none failed.""" + trader = self._ready() + if trader is None: + return False + result = trader.close_positions(symbol, ticket=ticket, comment=comment) + if isinstance(result, Err): + log.error("%s: closing %s: %s", self.log, symbol, result.error) + return False + if not result.value: + log.info("%s: there are no positions to close on %s", self.log, symbol) + return bool(result.value) + + def CancelOrders(self, symbol: str) -> None: + trader = self._ready() + if trader is None: + return + # 2.x only ever cancelled limit orders; stop orders stay untouched. + result = trader.cancel_pending_orders(symbol, kind=PendingKind.LIMIT) + if isinstance(result, Err): + log.error("%s: cancelling orders on %s: %s", self.log, symbol, result.error) + + def Disconnect(self) -> None: + if self._trader is not None: + self._trader.shutdown() + self._connected = False + log.info("Disconnected from MT5") + + # ---------------------------------------------------------------- helpers + + def _limit( + self, + side: Side, + symbol: str, + volume: float, + stoplimit: float, + *, + price: float | None, + comment: str | None, + ticket: int | None, + ) -> TradeReceipt | None: + trader = self._ready() + if trader is None or self._terminal is None or not _no_ticket(ticket): + return None + if price is not None: + log.error("%s: price has to be None for limit orders", self.log) + return None + tick = self._terminal.tick(symbol) + if isinstance(tick, Err): + log.error("%s: %s", self.log, tick.error) + return None + quote = tick.value.entry_price(side) + # 2.x semantics: a limit already reached by the market is filled at market. + crossed = quote <= stoplimit if side is Side.BUY else quote >= stoplimit + if crossed: + result = trader.open_position(symbol, side, volume, comment=comment) + else: + result = trader.place_limit_order(symbol, side, volume, stoplimit, comment=comment) + return self._receipt(result, f"{side.value} limit {symbol} @ {stoplimit}") + + def _ready(self) -> Trader | None: + if self._trader is None or not self._connected: + log.error("%s: not connected to MetaTrader 5; call login()", self.log) + return None + return self._trader + + def _receipt(self, result: Result[TradeReceipt, TradeError], what: str) -> TradeReceipt | None: + if isinstance(result, Ok): + log.info("%s: %s done", self.log, what) + return result.value + log.error("%s: %s failed: %s", self.log, what, result.error) + return result.error.receipt + + +def _legacy_stop(value: float | None, kind: str) -> Result[Stop | None, str]: + if value is None: + return Ok(None) + match (kind or "absolute").lower(): + case "absolute": + return Ok(Stop.at_price(value)) + case "offset": + return Ok(Stop.points(value)) + case other: + log.error("invalid stop type %r (use 'absolute' or 'offset')", other) + return Err(other) + + +def _no_ticket(ticket: int | None) -> bool: + if ticket is None: + return True + # 2.x forwarded it as `position` on an opening deal, which on hedging + # accounts turns an opposite-side entry into a close of that position. + log.error("the ticket argument is not supported for entries; use Close(ticket=...)") + return False + + +def _load_terminal() -> Terminal | None: + loaded = MetaTrader5Terminal.load() + if isinstance(loaded, Err): + log.error("%s", loaded.error) + return None + return loaded.value diff --git a/src/PythonMetaTrader5/legacy/views.py b/src/PythonMetaTrader5/legacy/views.py new file mode 100644 index 0000000..bf2e083 --- /dev/null +++ b/src/PythonMetaTrader5/legacy/views.py @@ -0,0 +1,51 @@ +"""Positions in the exact shapes the 2.x API returned.""" + +from __future__ import annotations + +from typing import Any, NamedTuple + +from PythonMetaTrader5.domain.market import Position +from PythonMetaTrader5.domain.orders import Side + +# MT5 POSITION_TYPE_BUY / POSITION_TYPE_SELL: 2.x callers compare `p.type == 0`. +_POSITION_TYPE = {Side.BUY: 0, Side.SELL: 1} + + +class LegacyPosition(NamedTuple): + """Attribute-compatible with MT5's TradePosition for the fields 2.x documented.""" + + ticket: int + symbol: str + type: int + volume: float + price_open: float + sl: float + tp: float + price_current: float + profit: float + time: int + magic: int + comment: str + + +def as_object(p: Position) -> LegacyPosition: + # Raw MT5 objects report a missing stop as 0.0; 2.x passed them through as is. + return LegacyPosition( + p.ticket, + p.symbol, + _POSITION_TYPE[p.side], + p.volume, + p.price_open, + p.sl or 0.0, + p.tp or 0.0, + p.price_current, + p.profit, + p.time, + p.magic, + p.comment, + ) + + +def as_dict(p: Position) -> dict[str, Any]: + # 2.x `as_dict=True` used None for a missing stop, unlike the raw objects. + return {**as_object(p)._asdict(), "sl": p.sl, "tp": p.tp} diff --git a/tests/unit/fake_mt5.py b/tests/unit/fake_mt5.py new file mode 100644 index 0000000..b8ff009 --- /dev/null +++ b/tests/unit/fake_mt5.py @@ -0,0 +1,129 @@ +"""A stand-in for the `MetaTrader5` module with its constants and call log.""" + +from __future__ import annotations + +from types import SimpleNamespace +from typing import Any + +CONSTANTS = { + "TRADE_ACTION_DEAL": 1, + "TRADE_ACTION_PENDING": 5, + "TRADE_ACTION_REMOVE": 8, + "ORDER_TYPE_BUY": 0, + "ORDER_TYPE_SELL": 1, + "ORDER_TYPE_BUY_LIMIT": 2, + "ORDER_TYPE_SELL_LIMIT": 3, + "ORDER_TYPE_BUY_STOP": 4, + "ORDER_TYPE_SELL_STOP": 5, + "ORDER_TYPE_BUY_STOP_LIMIT": 6, + "ORDER_TYPE_SELL_STOP_LIMIT": 7, + "ORDER_FILLING_FOK": 0, + "ORDER_FILLING_IOC": 1, + "ORDER_FILLING_RETURN": 2, + "ORDER_TIME_GTC": 0, + "POSITION_TYPE_BUY": 0, + "POSITION_TYPE_SELL": 1, +} + + +class FakeMT5: + def __init__(self) -> None: + for name, value in CONSTANTS.items(): + setattr(self, name, value) + self.calls: list[tuple[str, tuple[Any, ...], dict[str, Any]]] = [] + self.initialize_ok = True + self.error = (1, "Success") + self.symbols: dict[str, SimpleNamespace] = {} + self.ticks: dict[str, SimpleNamespace] = {} + self.send_result: SimpleNamespace | None = SimpleNamespace( + retcode=10009, + deal=11, + order=12, + volume=0.1, + price=1.1, + bid=1.1, + ask=1.2, + comment="Request executed", + request_id=13, + ) + self.positions: tuple[SimpleNamespace, ...] | None = () + self.orders: tuple[SimpleNamespace, ...] | None = () + + def _record(self, name: str, *args: Any, **kwargs: Any) -> None: + self.calls.append((name, args, kwargs)) + + def initialize(self, *args: Any, **kwargs: Any) -> bool: + self._record("initialize", *args, **kwargs) + return self.initialize_ok + + def last_error(self) -> tuple[int, str]: + return self.error + + def shutdown(self) -> None: + self._record("shutdown") + + def symbol_info(self, name: str) -> SimpleNamespace | None: + return self.symbols.get(name) + + def symbol_select(self, name: str, enable: bool) -> bool: + self._record("symbol_select", name, enable) + return True + + def symbol_info_tick(self, name: str) -> SimpleNamespace | None: + return self.ticks.get(name) + + def order_send(self, request: dict[str, Any]) -> SimpleNamespace | None: + self._record("order_send", request) + return self.send_result + + def positions_get(self, **kwargs: Any) -> tuple[SimpleNamespace, ...] | None: + self._record("positions_get", **kwargs) + return self.positions + + def orders_get(self, **kwargs: Any) -> tuple[SimpleNamespace, ...] | None: + self._record("orders_get", **kwargs) + return self.orders + + +def symbol_info(name: str = "EURUSD", visible: bool = True) -> SimpleNamespace: + return SimpleNamespace( + name=name, + visible=visible, + digits=5, + point=0.00001, + trade_tick_size=0.00001, + volume_min=0.01, + volume_max=100.0, + volume_step=0.01, + filling_mode=1, + trade_stops_level=10, + ) + + +def raw_position(ticket: int = 1, type_: int = 1, sl: float = 0.0) -> SimpleNamespace: + return SimpleNamespace( + ticket=ticket, + symbol="EURUSD", + type=type_, + volume=0.1, + price_open=1.1, + sl=sl, + tp=0.0, + price_current=1.09, + profit=5.0, + time=1700000000, + magic=42, + comment="bot", + ) + + +def raw_order(ticket: int = 5, type_: int = 3) -> SimpleNamespace: + return SimpleNamespace( + ticket=ticket, + symbol="EURUSD", + type=type_, + volume_current=0.2, + price_open=1.2, + magic=0, + comment="", + ) diff --git a/tests/unit/test_close_positions.py b/tests/unit/test_close_positions.py index faeaae2..e7adc9e 100644 --- a/tests/unit/test_close_positions.py +++ b/tests/unit/test_close_positions.py @@ -1,4 +1,5 @@ -from PythonMetaTrader5.application.trader import BatchFailure, Trader +from PythonMetaTrader5.application.batch import BatchFailure +from PythonMetaTrader5.application.trader import Trader from PythonMetaTrader5.domain.errors import ErrorKind from PythonMetaTrader5.domain.market import Position from PythonMetaTrader5.domain.orders import Side diff --git a/tests/unit/test_connection.py b/tests/unit/test_connection.py new file mode 100644 index 0000000..307af15 --- /dev/null +++ b/tests/unit/test_connection.py @@ -0,0 +1,68 @@ +import sys + +import pytest + +from PythonMetaTrader5 import Trader, connect +from PythonMetaTrader5.adapters import system_clock +from PythonMetaTrader5.adapters.mt5_terminal import MetaTrader5Terminal +from PythonMetaTrader5.domain.errors import ErrorKind +from PythonMetaTrader5.result import Err, Ok + +from .fake_mt5 import FakeMT5 + + +@pytest.fixture +def mt5(monkeypatch: pytest.MonkeyPatch) -> FakeMT5: + fake = FakeMT5() + monkeypatch.setitem(sys.modules, "MetaTrader5", fake) + return fake + + +def test_missing_package_is_reported_not_raised(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setitem(sys.modules, "MetaTrader5", None) + result = MetaTrader5Terminal.load() + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.CONNECTION_FAILED + + +def test_connect_returns_a_configured_trader(mt5: FakeMT5) -> None: + result = connect("123", "pw", "Demo", magic=7) + assert isinstance(result, Ok) + assert isinstance(result.value, Trader) + assert mt5.calls[0][2]["login"] == 123 + + +def test_connect_failure_is_an_error(mt5: FakeMT5) -> None: + mt5.initialize_ok = False + result = connect(123, "pw", "Demo") + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.CONNECTION_FAILED + + +def test_non_numeric_login_is_rejected_before_touching_the_terminal(mt5: FakeMT5) -> None: + result = connect("abc", "pw", "Demo") + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_ARGUMENT + assert mt5.calls == [] + + +def test_trader_is_a_context_manager_that_shuts_down(mt5: FakeMT5) -> None: + result = connect(1, "pw", "Demo") + assert isinstance(result, Ok) + with result.value as trader: + assert isinstance(trader, Trader) + assert mt5.calls[-1][0] == "shutdown" + + +def test_system_clock_sleeps(monkeypatch: pytest.MonkeyPatch) -> None: + slept: list[float] = [] + monkeypatch.setattr(system_clock.time, "sleep", slept.append) + system_clock.SystemClock().sleep(0.25) + assert slept == [0.25] + + +def test_connect_without_package_is_an_error(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setitem(sys.modules, "MetaTrader5", None) + result = connect(1, "pw", "Demo") + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.CONNECTION_FAILED diff --git a/tests/unit/test_failure_paths.py b/tests/unit/test_failure_paths.py index 0e59136..093109d 100644 --- a/tests/unit/test_failure_paths.py +++ b/tests/unit/test_failure_paths.py @@ -1,7 +1,8 @@ import pytest +from PythonMetaTrader5.application.batch import BatchFailure from PythonMetaTrader5.application.execution import RetryPolicy -from PythonMetaTrader5.application.trader import BatchFailure, Trader +from PythonMetaTrader5.application.trader import Trader from PythonMetaTrader5.domain.errors import ErrorKind, TradeError from PythonMetaTrader5.domain.market import Position from PythonMetaTrader5.domain.orders import Side diff --git a/tests/unit/test_legacy_broker.py b/tests/unit/test_legacy_broker.py new file mode 100644 index 0000000..32e11aa --- /dev/null +++ b/tests/unit/test_legacy_broker.py @@ -0,0 +1,157 @@ +"""The 2.x `Broker` API keeps its names, arguments and return shapes.""" + +import pytest + +from PythonMetaTrader5 import Broker +from PythonMetaTrader5.domain.errors import ErrorKind, TradeError +from PythonMetaTrader5.domain.market import PendingKind, PendingOrder, Position +from PythonMetaTrader5.domain.orders import Side +from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest + +from .fakes import FakeClock, FakeTerminal + + +@pytest.fixture +def broker(terminal: FakeTerminal, clock: FakeClock) -> Broker: + with pytest.warns(DeprecationWarning, match="connect"): + return Broker(123, "pw", "Demo", terminal=terminal, clock=clock) + + +def orders(terminal: FakeTerminal) -> list[OrderRequest]: + return [r for r in terminal.sent if isinstance(r, OrderRequest)] + + +def long_position(ticket: int = 1) -> Position: + return Position( + ticket=ticket, + symbol="EURUSD", + side=Side.BUY, + volume=0.1, + price_open=1.0, + sl=None, + tp=1.2, + price_current=1.0, + profit=3.0, + time=5, + magic=0, + comment="", + ) + + +def test_constructor_logs_in_with_string_credentials(terminal: FakeTerminal) -> None: + with pytest.warns(DeprecationWarning, match="connect"): + Broker("123", 456, "Demo", terminal=terminal, clock=FakeClock()) + (credentials,) = terminal.connected_with + assert (credentials.login, credentials.password, credentials.server) == (123, "456", "Demo") + + +def test_failed_login_is_logged_and_retried_by_login( + terminal: FakeTerminal, clock: FakeClock, caplog: pytest.LogCaptureFixture +) -> None: + terminal.connect_failure = TradeError(ErrorKind.CONNECTION_FAILED, "bad password") + with pytest.warns(DeprecationWarning, match="connect"): + broker = Broker(1, "pw", "Demo", terminal=terminal, clock=clock) + assert "bad password" in caplog.text + assert broker.login() is False + assert broker.OpenPosition("EURUSD", "buy", 0.1) is None + terminal.connect_failure = None + assert broker.login(ToEffect=True) is True + + +def test_open_position_with_offsets_returns_the_receipt( + broker: Broker, terminal: FakeTerminal +) -> None: + result = broker.OpenPosition( + "EURUSD", "long", 0.1, sl=1000, tp=1500, sl_type="offset", tp_type="offset" + ) + assert result is not None + assert result.retcode == 10009 + (request,) = orders(terminal) + assert (request.sl, request.tp) == (1.0901, 1.1151) + + +def test_wrappers_map_to_sides_and_absolute_stops(broker: Broker, terminal: FakeTerminal) -> None: + broker.Buy("EURUSD", 0.1) + broker.Sell("EURUSD", 0.1) + broker.BuySL("EURUSD", 0.1, 1.05) + broker.SellSL("EURUSD", 0.1, 100, sl_type="offset") + sides = [(r.side, r.sl) for r in orders(terminal)] + assert sides == [(Side.BUY, None), (Side.SELL, None), (Side.BUY, 1.05), (Side.SELL, 1.101)] + + +def test_broker_refusal_returns_the_receipt_and_logs_it( + broker: Broker, terminal: FakeTerminal, caplog: pytest.LogCaptureFixture +) -> None: + terminal.retcodes.append(10027) + result = broker.OpenPosition("EURUSD", "buy", 0.1) + assert result is not None + assert result.retcode == 10027 + assert "Algo Trading" in caplog.text + assert broker.RetCodes[10027] + + +@pytest.mark.parametrize( + "kwargs", + [{"side": "hold"}, {"sl": 1, "sl_type": "pips"}, {"tp": 1, "tp_type": "pips"}, {"ticket": 5}], +) +def test_unsupported_arguments_return_none(broker: Broker, kwargs: dict[str, object]) -> None: + arguments: dict[str, object] = {"side": "buy", **kwargs} + assert broker.OpenPosition("EURUSD", volume=0.1, **arguments) is None # type: ignore[arg-type] + + +def test_positions_keep_the_2x_shapes(broker: Broker, terminal: FakeTerminal) -> None: + terminal.open_positions = [long_position()] + (raw,) = broker.GetPositions() + assert (raw.ticket, raw.type, raw.sl, raw.tp) == (1, 0, 0.0, 1.2) + (as_dict,) = broker.GetPositionsBySymbol("EURUSD", as_dict=True) + assert (as_dict["type"], as_dict["sl"], as_dict["profit"]) == (0, None, 3.0) + assert broker.GetPosition(ticket=1, as_dict=True) == as_dict + assert broker.GetPosition("XAUUSD") is None + + +def test_close_returns_true_only_when_something_closed( + broker: Broker, terminal: FakeTerminal +) -> None: + assert broker.Close("EURUSD") is False + terminal.open_positions = [long_position()] + assert broker.Close("EURUSD") is True + terminal.retcodes.append(10018) + assert broker.Close("EURUSD", ticket=1) is False + + +def test_limit_crossing_the_market_executes_immediately( + broker: Broker, terminal: FakeTerminal +) -> None: + broker.BuyLimit("EURUSD", 0.1, stoplimit=1.2) # ask 1.1001 <= 1.2 + broker.SellLimit("EURUSD", 0.1, stoplimit=1.0) # bid 1.1 >= 1.0 + assert [(r.side, r.pending) for r in orders(terminal)] == [(Side.BUY, None), (Side.SELL, None)] + + +def test_limit_away_from_the_market_rests(broker: Broker, terminal: FakeTerminal) -> None: + terminal.retcodes.extend([10008, 10008]) + assert broker.BuyLimit("EURUSD", 0.1, stoplimit=1.05) is not None + assert broker.SellLimit("EURUSD", 0.1, stoplimit=1.15) is not None + assert [r.pending for r in orders(terminal)] == [PendingKind.LIMIT, PendingKind.LIMIT] + + +def test_limit_rejects_price_argument_and_missing_quote( + broker: Broker, terminal: FakeTerminal +) -> None: + assert broker.BuyLimit("EURUSD", 0.1, 1.05, price=1.0) is None + terminal.ticks.clear() + assert broker.SellLimit("EURUSD", 0.1, 1.15) is None + assert terminal.sent == [] + + +def test_cancel_orders_removes_only_limit_orders(broker: Broker, terminal: FakeTerminal) -> None: + def pending(ticket: int, kind: PendingKind) -> PendingOrder: + return PendingOrder(ticket, "EURUSD", Side.BUY, kind, 0.1, 1.0, 0, "") + + terminal.open_orders = [pending(5, PendingKind.LIMIT), pending(6, PendingKind.STOP)] + broker.CancelOrders("EURUSD") + assert terminal.sent == [CancelRequest(order=5)] + + +def test_disconnect_shuts_the_terminal_down(broker: Broker, terminal: FakeTerminal) -> None: + broker.Disconnect() + assert terminal.shut_down diff --git a/tests/unit/test_legacy_failures.py b/tests/unit/test_legacy_failures.py new file mode 100644 index 0000000..2e6b1cb --- /dev/null +++ b/tests/unit/test_legacy_failures.py @@ -0,0 +1,43 @@ +"""The 2.x facade degrades loudly: every failure is logged and returns 2.x's 'nothing'.""" + +import sys + +import pytest + +from PythonMetaTrader5 import Broker + +from .fakes import FakeClock +from .test_failure_paths import BrokenListing + + +def test_without_metatrader5_package_every_call_is_a_logged_no_op( + monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture +) -> None: + monkeypatch.setitem(sys.modules, "MetaTrader5", None) + with pytest.warns(DeprecationWarning, match="connect"): + broker = Broker(1, "pw", "Demo", clock=FakeClock()) + assert "not installed" in caplog.text + assert broker.login() is False + assert broker.GetPositions() == [] + assert broker.Close("EURUSD") is False + assert broker.BuyLimit("EURUSD", 0.1, 1.0) is None + assert broker.CancelOrders("EURUSD") is None + broker.Disconnect() + assert "not connected" in caplog.text + + +def test_listing_failures_are_logged(caplog: pytest.LogCaptureFixture) -> None: + with pytest.warns(DeprecationWarning, match="connect"): + broker = Broker(1, "pw", "Demo", terminal=BrokenListing(), clock=FakeClock()) + assert broker.GetPositions() == [] + assert broker.Close("EURUSD") is False + broker.CancelOrders("EURUSD") + assert caplog.text.count("orders_get failed") == 1 + assert caplog.text.count("positions_get failed") == 2 + + +def test_limit_with_ticket_is_refused(caplog: pytest.LogCaptureFixture) -> None: + with pytest.warns(DeprecationWarning, match="connect"): + broker = Broker(1, "pw", "Demo", terminal=BrokenListing(), clock=FakeClock()) + assert broker.SellLimit("EURUSD", 0.1, 1.0, ticket=3) is None + assert "Close(ticket=...)" in caplog.text diff --git a/tests/unit/test_mt5_adapter.py b/tests/unit/test_mt5_adapter.py new file mode 100644 index 0000000..02e21ff --- /dev/null +++ b/tests/unit/test_mt5_adapter.py @@ -0,0 +1,181 @@ +from types import SimpleNamespace + +import pytest + +from PythonMetaTrader5.adapters.mt5_terminal import MetaTrader5Terminal +from PythonMetaTrader5.application.ports import Credentials +from PythonMetaTrader5.domain.errors import ErrorKind +from PythonMetaTrader5.domain.market import PendingKind, Tick +from PythonMetaTrader5.domain.orders import Side +from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest +from PythonMetaTrader5.domain.symbol import Filling +from PythonMetaTrader5.result import Err, Ok + +from .fake_mt5 import FakeMT5, raw_order, raw_position, symbol_info + +CREDENTIALS = Credentials(login=123, password="secret", server="Demo", timeout_ms=5000) + + +@pytest.fixture +def mt5() -> FakeMT5: + return FakeMT5() + + +@pytest.fixture +def adapter(mt5: FakeMT5) -> MetaTrader5Terminal: + return MetaTrader5Terminal(mt5) + + +def last_sent(mt5: FakeMT5) -> dict[str, object]: + name, (request,), _ = mt5.calls[-1] + assert name == "order_send" + return request # type: ignore[no-any-return] + + +def test_connect_passes_credentials_and_reports_failure( + adapter: MetaTrader5Terminal, mt5: FakeMT5 +) -> None: + assert adapter.connect(CREDENTIALS) == Ok(None) + assert mt5.calls[0] == ( + "initialize", + (), + {"login": 123, "password": "secret", "server": "Demo", "timeout": 5000}, + ) + mt5.initialize_ok, mt5.error = False, (-6, "Authorization failed") + result = adapter.connect(Credentials(1, "p", "s", path="C:/mt5/terminal64.exe")) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.CONNECTION_FAILED + assert "Authorization failed" in result.error.message + assert "p" not in result.error.message.split() + assert mt5.calls[-1][1] == ("C:/mt5/terminal64.exe",) + + +def test_password_never_appears_in_repr() -> None: + assert "secret" not in repr(CREDENTIALS) + + +def test_symbol_is_mapped_and_hidden_symbols_are_selected( + adapter: MetaTrader5Terminal, mt5: FakeMT5 +) -> None: + mt5.symbols["EURUSD"] = symbol_info(visible=False) + result = adapter.symbol("EURUSD") + assert isinstance(result, Ok) + assert (result.value.digits, result.value.tick_size, result.value.stops_level) == (5, 1e-5, 10) + assert ("symbol_select", ("EURUSD", True), {}) in mt5.calls + missing = adapter.symbol("NOPE") + assert isinstance(missing, Err) + assert missing.error.kind is ErrorKind.SYMBOL_NOT_FOUND + + +def test_tick_requires_a_two_sided_quote(adapter: MetaTrader5Terminal, mt5: FakeMT5) -> None: + mt5.ticks["EURUSD"] = SimpleNamespace(bid=1.1, ask=1.2) + assert adapter.tick("EURUSD") == Ok(Tick(1.1, 1.2)) + mt5.ticks["EURUSD"] = SimpleNamespace(bid=0.0, ask=0.0) + for name in ("EURUSD", "NOPE"): + result = adapter.tick(name) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.NO_PRICE + + +def test_market_close_request_is_translated(adapter: MetaTrader5Terminal, mt5: FakeMT5) -> None: + request = OrderRequest( + symbol="EURUSD", + side=Side.SELL, + volume=0.1, + price=1.1, + filling=Filling.FOK, + deviation=10, + magic=42, + comment="x", + sl=1.2, + position=7, + ) + result = adapter.send(request) + assert isinstance(result, Ok) + assert (result.value.retcode, result.value.deal, result.value.request_id) == (10009, 11, 13) + assert last_sent(mt5) == { + "action": 1, + "symbol": "EURUSD", + "volume": 0.1, + "type": 1, + "price": 1.1, + "deviation": 10, + "magic": 42, + "comment": "x", + "type_filling": 0, + "type_time": 0, + "sl": 1.2, + "position": 7, + } + + +def test_pending_and_cancel_requests_are_translated( + adapter: MetaTrader5Terminal, mt5: FakeMT5 +) -> None: + adapter.send( + OrderRequest( + symbol="EURUSD", + side=Side.BUY, + volume=0.1, + price=1.0, + filling=Filling.RETURN, + deviation=10, + magic=0, + tp=1.1, + pending=PendingKind.LIMIT, + ) + ) + sent = last_sent(mt5) + assert (sent["action"], sent["type"], sent["type_filling"], sent["tp"]) == (5, 2, 2, 1.1) + assert "sl" not in sent + adapter.send(CancelRequest(order=99)) + assert last_sent(mt5) == {"action": 8, "order": 99} + + +def test_undeliverable_request_is_a_terminal_error( + adapter: MetaTrader5Terminal, mt5: FakeMT5 +) -> None: + mt5.send_result, mt5.error = None, (-2, 'Invalid "comment" argument') + result = adapter.send(CancelRequest(order=1)) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.TERMINAL_ERROR + assert "comment" in result.error.message + + +def test_positions_are_mapped_with_zero_stops_as_none( + adapter: MetaTrader5Terminal, mt5: FakeMT5 +) -> None: + mt5.positions = (raw_position(sl=1.2),) + result = adapter.positions(symbol="EURUSD") + assert isinstance(result, Ok) + (position,) = result.value + assert (position.side, position.sl, position.tp, position.magic) == (Side.SELL, 1.2, None, 42) + adapter.positions(ticket=1) + adapter.positions() + filters = [kwargs for name, _, kwargs in mt5.calls if name == "positions_get"] + assert filters == [{"symbol": "EURUSD"}, {"ticket": 1}, {}] + + +def test_pending_orders_skip_non_pending_types(adapter: MetaTrader5Terminal, mt5: FakeMT5) -> None: + mt5.orders = (raw_order(5, type_=3), raw_order(6, type_=0), raw_order(7, type_=4)) + result = adapter.pending_orders(symbol="EURUSD") + assert isinstance(result, Ok) + kinds = [(o.ticket, o.side, o.kind, o.volume) for o in result.value] + assert kinds == [(5, Side.SELL, PendingKind.LIMIT, 0.2), (7, Side.BUY, PendingKind.STOP, 0.2)] + + +def test_listing_distinguishes_empty_from_failure( + adapter: MetaTrader5Terminal, mt5: FakeMT5 +) -> None: + mt5.positions = mt5.orders = None + assert adapter.positions() == Ok([]) + assert adapter.pending_orders() == Ok([]) + mt5.error = (-10004, "No IPC connection") + for result in (adapter.positions(), adapter.pending_orders()): + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.TERMINAL_ERROR + + +def test_shutdown_is_forwarded(adapter: MetaTrader5Terminal, mt5: FakeMT5) -> None: + adapter.shutdown() + assert mt5.calls[-1][0] == "shutdown" diff --git a/tests/unit/test_pending_orders.py b/tests/unit/test_pending_orders.py index c360c59..5c38e4c 100644 --- a/tests/unit/test_pending_orders.py +++ b/tests/unit/test_pending_orders.py @@ -75,3 +75,19 @@ def test_invalid_limit_order_never_reaches_the_terminal( assert isinstance(result, Err) assert result.error.kind is ErrorKind.INVALID_VOLUME assert terminal.sent == [] + + +def test_cancel_can_be_limited_to_one_order_kind(trader: Trader, terminal: FakeTerminal) -> None: + stop = PendingOrder( + ticket=8, + symbol="EURUSD", + side=Side.SELL, + kind=PendingKind.STOP, + volume=0.1, + price=1.0, + magic=42, + comment="", + ) + terminal.open_orders = [order(5, "EURUSD"), stop] + trader.cancel_pending_orders("EURUSD", kind=PendingKind.LIMIT) + assert terminal.sent == [CancelRequest(order=5)] From 6e7cbee2cf618f83706c2622c97127ec23fa987d Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 02:02:13 +0100 Subject: [PATCH 05/28] ci: add CI gates, file-length check and demo-account integration tests - Unit tests, ruff and mypy --strict on Python 3.10-3.14 (Linux). - A Windows job installs the real MetaTrader5 wheel and builds the adapter against it, so a renamed constant fails CI instead of a live order. - Semgrep: ERROR (high/critical) findings block the merge; WARNING (medium) findings are listed for the PR description. - scripts/check_file_length.py enforces the 300-line limit on tracked files. - Package build + twine check --strict. - Actions pinned to commit SHAs so a moved tag cannot inject code. - Integration tests run only with MT5_* credentials and refuse to trade on a non-demo account; they use a dedicated magic number for cleanup. --- .github/workflows/ci.yml | 72 +++++++++++++++++++ scripts/check_file_length.py | 34 +++++++++ tests/integration/test_demo_account.py | 99 ++++++++++++++++++++++++++ 3 files changed, 205 insertions(+) create mode 100644 .github/workflows/ci.yml create mode 100644 scripts/check_file_length.py create mode 100644 tests/integration/test_demo_account.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..7cc6d8f --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,72 @@ +name: CI + +on: + pull_request: + push: + branches: [master] + +permissions: + contents: read + +concurrency: + group: ci-${{ github.ref }} + cancel-in-progress: true + +jobs: + test: + name: lint, types, unit tests (py${{ matrix.python }}) + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + python: ["3.10", "3.11", "3.12", "3.13", "3.14"] + steps: + # Actions are pinned to commit SHAs: a moved tag cannot inject code into CI. + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 + with: + python-version: ${{ matrix.python }} + - run: python -m pip install -e ".[dev]" + - run: ruff check src tests scripts + - run: ruff format --check src tests scripts + - run: mypy + - run: pytest --cov --cov-report=term-missing + + windows-mt5: + # The real MetaTrader5 wheel exists only on Windows; this proves the adapter + # matches the constants of the installed package, not just our fake. + name: real MetaTrader5 package (Windows) + runs-on: windows-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 + with: + python-version: "3.12" + - run: python -m pip install -e ".[dev]" + - run: python -c "import MetaTrader5 as m; from PythonMetaTrader5.adapters.mt5_terminal import MetaTrader5Terminal as T; T(m); print('MetaTrader5', m.__version__)" + - run: pytest + + semgrep: + name: static analysis (Semgrep) + runs-on: ubuntu-latest + container: + image: semgrep/semgrep + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + # ERROR-severity (high/critical) findings fail the job and block the merge. + - run: semgrep scan --config p/python --config p/secrets --config p/github-actions --severity ERROR --error + # WARNING-severity (medium) findings are listed for the PR description, not blocking. + - run: semgrep scan --config p/python --config p/secrets --config p/github-actions --severity WARNING + + hygiene: + name: file length, package build + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 + with: + python-version: "3.12" + - run: python scripts/check_file_length.py + - run: python -m pip install build twine + - run: python -m build + - run: twine check --strict dist/* diff --git a/scripts/check_file_length.py b/scripts/check_file_length.py new file mode 100644 index 0000000..0395dc9 --- /dev/null +++ b/scripts/check_file_length.py @@ -0,0 +1,34 @@ +"""Fail when a tracked, hand-written text file exceeds the project's line limit.""" + +from __future__ import annotations + +import subprocess +import sys +from pathlib import Path + +MAX_LINES = 300 +# Binary or third-party verbatim files; nothing generated is tracked. +EXEMPT_SUFFIXES = {".png", ".jpg", ".ico", ".whl"} + + +def tracked_files() -> list[Path]: + # S603: the command is a constant, no untrusted input reaches the process. + command = ["git", "ls-files"] + output = subprocess.run(command, check=True, capture_output=True, text=True).stdout # noqa: S603 + return [Path(line) for line in output.splitlines() if line] + + +def main() -> int: + offenders = [] + for path in tracked_files(): + if path.suffix in EXEMPT_SUFFIXES or not path.is_file(): + continue + count = len(path.read_text(encoding="utf-8", errors="replace").splitlines()) + if count > MAX_LINES: + offenders.append(f"{path}: {count} lines (limit {MAX_LINES})") + print("\n".join(offenders) or f"all tracked files have <= {MAX_LINES} lines") + return 1 if offenders else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/integration/test_demo_account.py b/tests/integration/test_demo_account.py new file mode 100644 index 0000000..7892540 --- /dev/null +++ b/tests/integration/test_demo_account.py @@ -0,0 +1,99 @@ +"""End-to-end checks against a real MetaTrader 5 terminal on a DEMO account. + +Run locally on Windows with a terminal installed: + + set MT5_LOGIN=... & set MT5_PASSWORD=... & set MT5_SERVER=... + pytest -m integration + +Optional: MT5_SYMBOL (default EURUSD), MT5_PATH (terminal64.exe). +These tests place and close real orders, so they refuse to run on anything +but a demo account. +""" + +from __future__ import annotations + +import os +from collections.abc import Iterator + +import pytest + +from PythonMetaTrader5 import Err, ErrorKind, Ok, PendingKind, Side, Stop, Trader, connect + +pytestmark = pytest.mark.integration +# Windows-only package: the whole module is skipped where it cannot be installed. +mt5 = pytest.importorskip("MetaTrader5") + +REQUIRED = ("MT5_LOGIN", "MT5_PASSWORD", "MT5_SERVER") +# Distinct from any manual trading so cleanup never touches foreign positions. +MAGIC = 930_117 +SYMBOL = os.environ.get("MT5_SYMBOL", "EURUSD") + + +@pytest.fixture(scope="module") +def trader() -> Iterator[Trader]: + if any(name not in os.environ for name in REQUIRED): + pytest.skip("MT5_LOGIN / MT5_PASSWORD / MT5_SERVER not set") + result = connect( + os.environ["MT5_LOGIN"], + os.environ["MT5_PASSWORD"], + os.environ["MT5_SERVER"], + path=os.environ.get("MT5_PATH"), + magic=MAGIC, + ) + if isinstance(result, Err): + pytest.fail(f"cannot connect: {result.error}") + account = mt5.account_info() + if account is None or account.trade_mode != mt5.ACCOUNT_TRADE_MODE_DEMO: + result.value.shutdown() + pytest.fail("refusing to trade: the account is not a demo account") + yield result.value + result.value.close_positions(magic=MAGIC) + result.value.cancel_pending_orders(magic=MAGIC) + result.value.shutdown() + + +def minimum_volume() -> float: + return float(mt5.symbol_info(SYMBOL).volume_min) + + +def test_open_and_close_a_market_position(trader: Trader) -> None: + opened = trader.open_position( + SYMBOL, + Side.BUY, + minimum_volume(), + sl=Stop.points(2000), + tp=Stop.points(2000), + comment="pmt5 integration", + ) + if isinstance(opened, Err) and opened.error.kind is ErrorKind.MARKET_CLOSED: + pytest.skip("market closed") + assert isinstance(opened, Ok), opened + positions = trader.positions(SYMBOL, magic=MAGIC) + assert isinstance(positions, Ok) + assert len(positions.value) == 1 + position = positions.value[0] + assert position.sl is not None + assert position.tp is not None + closed = trader.close_positions(ticket=position.ticket) + assert isinstance(closed, Ok), closed + assert trader.positions(SYMBOL, magic=MAGIC) == Ok([]) + + +def test_place_and_cancel_a_limit_order_far_from_the_market(trader: Trader) -> None: + bid = mt5.symbol_info_tick(SYMBOL).bid + placed = trader.place_limit_order(SYMBOL, Side.BUY, minimum_volume(), bid * 0.9) + if isinstance(placed, Err) and placed.error.kind is ErrorKind.MARKET_CLOSED: + pytest.skip("market closed") + assert isinstance(placed, Ok), placed + pending = trader.pending_orders(SYMBOL, magic=MAGIC, kind=PendingKind.LIMIT) + assert isinstance(pending, Ok) + assert len(pending.value) == 1 + cancelled = trader.cancel_pending_orders(SYMBOL, magic=MAGIC) + assert isinstance(cancelled, Ok), cancelled + assert trader.pending_orders(SYMBOL, magic=MAGIC) == Ok([]) + + +def test_oversized_comment_is_rejected_locally(trader: Trader) -> None: + result = trader.open_position(SYMBOL, Side.BUY, minimum_volume(), comment="x" * 32) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_ARGUMENT From 252c68d6657788762f465ba86c72eb72bc66883e Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 02:05:03 +0100 Subject: [PATCH 06/28] docs: rewrite README, add migration guide, changelog, architecture and ADRs ADRs record each decision as 'A over B because B silently breaks C': ports per process boundary, Result at boundaries, bounded retries with no retry on unknown outcome, no GUI automation, stdlib logging without a NullHandler, the 2.x facade, filling mode and tick-grid pricing. --- CHANGELOG.md | 46 +++ MIGRATION.md | 62 ++++ README.md | 339 ++++++------------ .../0001-ports-only-at-process-boundaries.md | 24 ++ docs/adr/0002-result-at-boundaries.md | 25 ++ docs/adr/0003-bounded-retries.md | 25 ++ docs/adr/0004-no-gui-automation.md | 22 ++ docs/adr/0005-stdlib-logging.md | 24 ++ docs/adr/0006-legacy-facade.md | 27 ++ docs/adr/0007-filling-and-price-grid.md | 24 ++ docs/architecture.md | 52 +++ 11 files changed, 443 insertions(+), 227 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 MIGRATION.md create mode 100644 docs/adr/0001-ports-only-at-process-boundaries.md create mode 100644 docs/adr/0002-result-at-boundaries.md create mode 100644 docs/adr/0003-bounded-retries.md create mode 100644 docs/adr/0004-no-gui-automation.md create mode 100644 docs/adr/0005-stdlib-logging.md create mode 100644 docs/adr/0006-legacy-facade.md create mode 100644 docs/adr/0007-filling-and-price-grid.md create mode 100644 docs/architecture.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..78c3b16 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,46 @@ +# Changelog + +All notable changes to this project are documented here. The format follows +[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses +[Semantic Versioning](https://semver.org/). + +## [3.0.0] - Unreleased + +Complete rewrite. See [MIGRATION.md](MIGRATION.md) for every behaviour change. + +### Added +- `connect()` and the `Trader` API returning `Result` (`Ok` / `Err`) values. +- Typed errors (`TradeError`, `ErrorKind`) and `BatchFailure` for close-all / + cancel-all with per-ticket outcomes. +- `Stop.points()` / `Stop.at_price()` for SL/TP; plain floats are prices. +- Magic-number support for entries and as a filter for close/cancel/queries. +- Volume validation against the symbol's min/max/step. +- Filling mode chosen from the symbol's allowed modes. +- Hidden symbols are selected into Market Watch automatically. +- `py.typed`: the package ships type information. +- CI: ruff, mypy --strict, tests on Python 3.10-3.14, a Windows job against the + real `MetaTrader5` package, Semgrep, a 300-line file limit, build checks. +- Integration tests against a demo account. + +### Changed +- `Broker` is a deprecated facade over `Trader` with the 2.x method names. +- Bounded retries (requotes only) instead of endless loops. +- Prices snap to the symbol's tick size instead of rounding to `digits`. +- Logging moved from `loguru` to the standard `logging` module. +- Minimum Python version is 3.10. +- License metadata is CC-BY-NC-4.0 (the MIT classifier was wrong). + +### Removed +- `pyautogui` Ctrl+E hotkey on retcode 10027. +- The `from MetaTrader5 import *` re-export. +- The `Broker.password` attribute. + +### Fixed +- `Close(ticket=...)` with `symbol=None` crashed. +- `CancelOrders` and `Close` could loop forever. +- Limit orders confirmed with `PLACED` (10008) were re-sent. +- `len(None)` crash when the terminal returned no positions. + +## [2.3.2] + +Last release of the 2.x line. diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000..51b173b --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,62 @@ +# Migrating from 2.x to 3.0 + +3.0 is a rewrite. Existing code using `Broker` keeps running, but the behaviours +below changed on purpose because they were unsafe. Read this list before +upgrading a bot that trades real money. + +## Requirements + +- Python **3.10+** (2.x claimed 3.6+). +- `pyautogui` and `loguru` are no longer dependencies. + +## Behaviour changes in `Broker` + +| 2.x | 3.0 | Why | +|---|---|---| +| `OpenPosition`, `BuyLimit`, `SellLimit` retried **forever** on any unknown retcode (e.g. no money, invalid volume, market closed over the weekend), sending an order every 0.5 s | Requotes retried at most 3 times; every other failure returns at once (the receipt is returned, the error is logged) | A weekend webhook would block the bot until Monday; a rejected order was re-sent indefinitely | +| On retcode 10027 it pressed **Ctrl+E** via `pyautogui` | Logs "enable Algo Trading" and returns the receipt | Ctrl+E *toggles* Algo Trading and is typed into whichever window has focus | +| `Close()` always returned `False` | `True` if at least one position closed and none failed, else `False` | The return value was meaningless | +| `Close(symbol=None, ticket=...)` crashed | Each position is closed on its own symbol | It priced the close with the `symbol` argument | +| `CancelOrders` could loop forever on a failed cancel | One attempt per order (requotes retried), failures logged | Same as above | +| Comments longer than 31 characters made `order_send` fail with `None` | Rejected before sending, logged | Explicit error instead of a crash downstream | +| `ticket=` on `OpenPosition`/`Buy`/`Sell`/`BuyLimit`/`SellLimit` was forwarded as `position` | Refused: returns `None`, logs an error | On hedging accounts it turned an entry into a close of that position | +| Retcode 10008 (`PLACED`) for limit orders was treated as failure and re-sent | Treated as success | Limit orders could be placed more than once | +| Prices rounded to `digits` | Prices snapped to the symbol's tick size | Symbols with tick 0.25 were rejected | +| Fixed FOK (open) / IOC (close) filling | Filling chosen from the symbol's allowed modes (FOK > IOC > RETURN) | Brokers without FOK rejected every order (10030) | +| `broker.password` attribute | Removed; credentials are kept in a non-printing object | The password showed up in debug dumps | +| `GetPositions()` returned raw MT5 objects | Returns `LegacyPosition` named tuples with the same fields (`ticket`, `type`, `sl`, ...) | Same attribute access; no dependency on MT5 internals | + +## Removed: `from MetaTrader5 import *` re-export + +2.x re-exported the whole `MetaTrader5` namespace, so +`from PythonMetaTrader5 import *` also gave you `symbol_info`, `ORDER_TYPE_BUY` +and friends. Import those from the official package instead: + +```python +import MetaTrader5 as mt5 +info = mt5.symbol_info("EURUSD") +``` + +## Logging + +2.x printed through `loguru`. 3.0 uses the standard `logging` module (logger +`PythonMetaTrader5`). Errors and warnings still reach stderr without any +configuration; to see info messages: + +```python +import logging +logging.basicConfig(level=logging.INFO) +``` + +## Moving to the 3.0 API + +| 2.x | 3.0 | +|---|---| +| `Broker(login, password, server)` | `connect(login, password, server)` → `Ok(trader)` / `Err(error)` | +| `OpenPosition(s, "buy", v, sl=1000, sl_type="offset")` | `trader.open_position(s, "buy", v, sl=Stop.points(1000))` | +| `OpenPosition(s, "buy", v, sl=1.05)` | `trader.open_position(s, "buy", v, sl=1.05)` | +| `Close("EURUSD")` | `trader.close_positions("EURUSD")` | +| `BuyLimit(s, v, stoplimit=1.1)` | `trader.place_limit_order(s, "buy", v, 1.1)` (no automatic market fill when crossed) | +| `CancelOrders(s)` | `trader.cancel_pending_orders(s, kind=PendingKind.LIMIT)` | +| `GetPositions(as_dict=True)` | `[p.to_dict() for p in trader.positions().value]` | +| `Disconnect()` | `trader.shutdown()` or `with trader:` | diff --git a/README.md b/README.md index f7c3c10..7ff616e 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,32 @@ -# PythonMetaTrader5 [![PyPI Publish](https://github.com/Akinzou/MetaTrader5-Python/actions/workflows/python-publish.yml/badge.svg)](https://github.com/Akinzou/MetaTrader5-Python/actions/workflows/python-publish.yml) ![PyPI](https://img.shields.io/pypi/v/pythonmetatrader5) ![Python](https://img.shields.io/badge/python-3.6%2B-blue?logo=python&logoColor=white) ![License](https://img.shields.io/badge/license-CC_BY--NC_4.0-lightgrey.svg) [![PyPI Downloads](https://static.pepy.tech/badge/pythonmetatrader5)](https://pepy.tech/projects/pythonmetatrader5) - -[![Discord](https://img.shields.io/badge/Join_us_on-Discord-5865F2?logo=discord&logoColor=white&style=for-the-badge)](https://discord.gg/BARYa55KS8) - - -# MetaTrader5 Python Broker Helper - -Minimal, production‑ready helper around the official **MetaTrader5** Python package, -with a single market-entry function and clean handling of **SL/TP as absolute prices or offsets in POINTS**. -Includes utilities to read positions, close them, and manage pending orders. - -> Works with: `MetaTrader5`, `loguru`, `pyautogui` - ---- - -## Features - -* **Unified Execution Engine**: Single core function to open market positions (`OpenPosition(...)`). -* **Dynamic Risk Management**: SL/TP can be passed as **absolute prices** or flexible **offsets in POINTS**. -* **Input Sanitization**: Automatic price normalization to the correct instrument `digits`, preventing API rejection. -* **Robust Telemetry**: Consistent error handling with common MT5 `retcodes` mapped to readable messages. -* **Backward Compatibility**: Seamless wrappers for legacy integration (`Buy`, `Sell`, `BuySL`, `SellSL`). -* **State Helpers**: Efficient querying tools for current market exposure (`GetPositions`, `GetPosition`, `GetPositionsBySymbol`). -* **Lifecycle Management**: Complete control over active and pending trades (`Close`, `SellLimit`, `BuyLimit`, `CancelOrders`). - ---- +# PythonMetaTrader5 + +[![CI](https://github.com/Akinzou/MetaTrader5-Python/actions/workflows/ci.yml/badge.svg)](https://github.com/Akinzou/MetaTrader5-Python/actions/workflows/ci.yml) +[![PyPI](https://img.shields.io/pypi/v/pythonmetatrader5)](https://pypi.org/project/PythonMetaTrader5/) +![Python](https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white) +![License](https://img.shields.io/badge/license-CC_BY--NC_4.0-lightgrey.svg) +[![PyPI Downloads](https://static.pepy.tech/badge/pythonmetatrader5)](https://pepy.tech/projects/pythonmetatrader5) +[![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/BARYa55KS8) + +A safe, typed trading layer over the official +[`MetaTrader5`](https://pypi.org/project/MetaTrader5/) Python package. + +Built for bots (webhook executors, signal followers) where a trading call must +**never hang, never retry blindly, and never fail silently**: + +- **Every call returns.** Requotes are retried a bounded number of times with a + fresh quote; everything else comes back immediately as a typed error. +- **No double fills.** Timeouts and lost connections are never auto-retried: + the order may already be live. +- **Typed results.** `Ok(receipt)` or `Err(TradeError)` with an `ErrorKind` + (`MARKET_CLOSED`, `NO_MONEY`, `INVALID_STOPS`, ...) instead of magic numbers. +- **Correct prices and lots.** Prices snap to the symbol's tick grid, volumes + are checked against min/max/step, the filling mode is chosen from the symbol. +- **Magic numbers.** Tag your bot's trades and close/cancel only those. +- **SL/TP as prices or distances in points.** +- **2.x compatible.** The old `Broker` class still works (deprecated). + +> Requires Windows with a MetaTrader 5 terminal installed (the official +> `MetaTrader5` package is Windows-only). Enable **Algo Trading** in the terminal. ## Installation @@ -31,224 +34,106 @@ Includes utilities to read positions, close them, and manage pending orders. pip install PythonMetaTrader5 ``` -> Ensure your MetaTrader 5 terminal is running, logged in, and **Algo Trading** is enabled. - ---- - -## Quick Start +## Quick start ```python -from PythonMetaTrader5 import Broker -import time - -# Login to your account -broker = Broker(96540048, "PASSWORD", "MetaQuotes-Demo") -time.sleep(1) # small grace period after login - -# Open BUY with SL/TP given as OFFSETS IN POINTS -r = broker.OpenPosition( - "EURUSD", "buy", 0.10, - sl=1000, sl_type="offset", # 1000 points (≈ 100 pips on 5-digit symbol) - tp=1500, tp_type="offset" -) - -# Read positions for a symbol -xau_positions = broker.GetPositionsBySymbol("XAUUSD", as_dict=True) - -# Close all positions on a symbol -broker.Close("EURUSD") - -# Cancel pending limit orders on a symbol -broker.CancelOrders("EURUSD") - -# Graceful shutdown -broker.Disconnect() +from PythonMetaTrader5 import Err, Ok, Side, Stop, connect + +match connect(12345678, "password", "MetaQuotes-Demo", magic=1001): + case Err(error): + raise SystemExit(f"cannot connect: {error}") + case Ok(trader): + pass + +with trader: # shuts the terminal connection down on exit + result = trader.open_position( + "EURUSD", Side.BUY, 0.10, + sl=Stop.points(1000), # 1000 points below the entry price + tp=1.12500, # a plain float is an absolute price + comment="webhook #42", + ) + match result: + case Ok(receipt): + print("filled at", receipt.price, "deal", receipt.deal) + case Err(error): + print("not opened:", error.kind, error.message) + + trader.close_positions("EURUSD", magic=1001) # only this bot's positions ``` ---- - -## SL/TP Semantics (Important) - -- `sl_type` / `tp_type`: - - `"absolute"` → you pass **absolute prices** (e.g., `1.23456`) - - `"offset"` → you pass **offsets in POINTS** (converted using `symbol_info(symbol).point`) - -- Offsets are applied from the **current tick price** (`ask` for BUY, `bid` for SELL): - - BUY : `SL = ask - |sl|*point`, `TP = ask + |tp|*point` - - SELL: `SL = bid + |sl|*point`, `TP = bid - |tp|*point` - -- All calculated prices (including absolute inputs) are normalized to the instrument `digits`. - -> If you get `Wrong SL (10016)`, check `symbol_info(symbol).stops_level` and multiply by `point` to know the minimal allowed distance. - ---- - -## API Reference - -### `class Broker` - -#### `__init__(self, log, password, server)` -Initialize MT5, attempt login, and print account info on success. - -- **log**: login number (int or str) -- **password**: account password (str) -- **server**: broker server name (str) - -#### `login(self, ToEffect=False) -> bool` -Retrying login loop. If `ToEffect` is `False`, returns immediately on failure. - ---- - -### Market Entry - -#### `OpenPosition(self, symbol, side, volume, *, sl=None, tp=None, price=None, comment=None, ticket=None, sl_type="absolute", tp_type="absolute")` -Open a market position. - -- **symbol**: e.g., `"EURUSD"` -- **side**: `"buy" | "sell" | "long" | "short"` -- **volume**: lot size (float) -- **sl**/**tp**: number (see `sl_type`/`tp_type`) -- **sl_type**/**tp_type**: `"absolute"` (prices) or `"offset"` (**POINTS**) -- **price**: optional direct price; if `None`, uses current tick (ask/bid) and retries on transient errors -- **comment**: optional MT5 order comment -- **ticket**: existing position id if needed (rarely used for market entry) - -**Returns**: result of `order_send` (MT5 `TradeResult`) +## API + +`connect(login, password, server, *, path=None, timeout_ms=60000, magic=0, +deviation=10, retry=None) -> Result[Trader, TradeError]` + +| `Trader` method | Returns | +|---|---| +| `open_position(symbol, side, volume, *, sl=None, tp=None, price=None, comment=None)` | `Result[TradeReceipt, TradeError]` | +| `place_limit_order(symbol, side, volume, price, *, sl=None, tp=None, comment=None)` | `Result[TradeReceipt, TradeError]` | +| `close_positions(symbol=None, *, ticket=None, magic=None, comment=None)` | `Result[list[TradeReceipt], BatchFailure]` | +| `cancel_pending_orders(symbol=None, *, magic=None, kind=None)` | `Result[list[TradeReceipt], BatchFailure]` | +| `positions(symbol=None, *, ticket=None, magic=None)` | `Result[list[Position], TradeError]` | +| `pending_orders(symbol=None, *, magic=None, kind=None)` | `Result[list[PendingOrder], TradeError]` | +| `shutdown()` | `None` | + +- `side`: `Side.BUY` / `Side.SELL`, or the strings `"buy"`, `"sell"`, `"long"`, `"short"`. +- `sl` / `tp`: a float is an **absolute price**; `Stop.points(n)` is a distance + of `n` points from the entry price (`Stop.at_price(p)` is the explicit form). + For limit orders the distance is measured from the limit price. +- `price` (market orders): send at this price once instead of the live quote. +- `comment`: at most 31 characters (the terminal's limit). Longer comments are + rejected, not truncated. +- `BatchFailure.succeeded` / `.errors` tell exactly which tickets closed and + which did not; each `TradeError.ticket` names the position/order. + +### Errors + +`TradeError(kind, message, retcode=None, receipt=None, ticket=None)`. The +`receipt` carries the broker's raw answer when there was one. Retry policy: + +| Server answer | What happens | +|---|---| +| done, placed, partial fill | `Ok(receipt)` | +| requote, price changed, no quotes, too many requests | retried with a fresh quote, up to `RetryPolicy.attempts` (default 3, 0.5 s apart), then `RETRIES_EXHAUSTED` | +| timeout, no connection | `OUTCOME_UNKNOWN`, never retried: check `positions()` first | +| anything else | the matching `ErrorKind`, returned at once | -**Examples**: ```python -# Absolute prices -broker.OpenPosition("XAUUSD", "sell", 0.10, sl=2400.0, tp=2380.0, sl_type="absolute", tp_type="absolute") +from PythonMetaTrader5 import RetryPolicy, connect -# Offsets in POINTS -broker.OpenPosition("EURUSD", "buy", 0.10, sl=1000, tp=1500, sl_type="offset", tp_type="offset") +connect(..., retry=RetryPolicy(attempts=5, delay_seconds=0.2)) ``` ---- +### Logging -### Backward‑Compat Wrappers +The library logs through the standard `logging` module under the +`PythonMetaTrader5` logger and never configures handlers itself. Without any +logging configuration, warnings and errors still reach stderr. -#### `Buy(self, symbol, volume, price=None, *, comment=None, ticket=None)` -Market BUY via `OpenPosition`. +## Migrating from 2.x -#### `Sell(self, symbol, volume, price=None, *, comment=None, ticket=None)` -Market SELL via `OpenPosition`. +`from PythonMetaTrader5 import Broker` keeps working and emits a +`DeprecationWarning`. Several 2.x behaviours were unsafe and changed: see +[MIGRATION.md](MIGRATION.md). -#### `BuySL(self, symbol, volume, sl, price=None, *, comment=None, ticket=None, sl_type="absolute")` -BUY with SL specified (absolute or offset in points). +## Development -#### `SellSL(self, symbol, volume, sl, price=None, *, comment=None, ticket=None, sl_type="absolute")` -SELL with SL specified (absolute or offset in points). - ---- - -### Close & Pending Orders - -#### `Close(self, symbol, *, comment=None, ticket=None) -> bool` -Iteratively closes all positions for a **ticket** or for a **symbol** (same filtering semantics as `positions_get`). Returns `False` if nothing to close. - -#### `SellLimit(self, symbol, volume, stoplimit, price=None, comment=None, ticket=None)` -Create a SELL LIMIT order at `stoplimit`. If current `bid >= stoplimit`, executes a market SELL immediately for consistency. - -#### `BuyLimit(self, symbol, volume, stoplimit, price=None, comment=None, ticket=None)` -Create a BUY LIMIT order at `stoplimit`. If current `ask <= stoplimit`, executes a market BUY immediately. - -#### `CancelOrders(self, symbol)` -Cancel all BUY/SELL LIMIT pending orders on the given symbol. - -#### `Disconnect(self)` -Shutdown MT5 connection. - ---- - -### Positions Helpers - -#### `GetPositionsBySymbol(self, symbol: str, as_dict: bool = False) -> list` -Return all open positions for a symbol. If `as_dict=True`, returns a list of plain dictionaries (ready for JSON/GUI). - -#### `GetPositions(self, symbol=None, *, ticket=None, as_dict: bool = False) -> list` -Return positions with the same filter style as `Close()`: -- `ticket` provided → that single position -- else `symbol` provided → all for that symbol -- else → all positions - -#### `GetPosition(self, symbol=None, *, ticket=None, as_dict: bool = False)` -Return the first matching position (or `None`). Useful when at most one position is expected. - -**Example**: -```python -p = broker.GetPosition(symbol="XAUUSD", as_dict=True) -if p: - print("Ticket:", p["ticket"], "Type:", "BUY" if p["type"] == 0 else "SELL", "Profit:", p["profit"]) -``` - ---- - -## Error Handling & Retcodes - -- Known retcodes are mapped in `RetCodes`: - - `10027`: Enable Algo Trading in MetaTrader5 app - - `10018`: Market closed - - `10016`: Wrong SL - -- For `10027`, a `Ctrl+E` hotkey is issued via `pyautogui` to toggle Algo Trading. -- For `10016`, retries are **not** attempted (invalid SL/TP). - ---- - -## Advanced Examples - -```python -# 1) BUY with SL absolute price, TP as offset in points -broker.OpenPosition( - "US500", "buy", 1.0, - sl=5780.0, sl_type="absolute", - tp=200, tp_type="offset" -) - -# 2) SELL with both offsets in points -broker.OpenPosition( - "EURUSD", "sell", 0.2, - sl=800, tp=1200, - sl_type="offset", tp_type="offset" -) - -# 3) Get all positions as dicts and filter by profit -pos = broker.GetPositions(as_dict=True) -winners = [p for p in pos if p["profit"] > 0] - -# 4) Close by ticket -p = broker.GetPosition(symbol="XAUUSD") -if p: - broker.Close("XAUUSD", ticket=p.ticket) - -# 5) Pending orders -broker.BuyLimit("EURUSD", 0.10, stoplimit=1.10000) -broker.SellLimit("EURUSD", 0.10, stoplimit=1.12000) -broker.CancelOrders("EURUSD") +```bash +python -m venv .venv && .venv\Scripts\activate +pip install -e ".[dev]" +ruff check src tests scripts && ruff format --check src tests scripts +mypy +pytest --cov ``` ---- - -## Notes +Integration tests trade on a **demo** account and are skipped unless +`MT5_LOGIN`, `MT5_PASSWORD` and `MT5_SERVER` are set (they refuse to run on a +live account): `pytest -m integration`. -- Ensure the symbol is visible/active in MT5 Market Watch. -- Check `stops_level`/`freeze_level` on your broker if SL/TP are rejected: - ```python - info = symbol_info("EURUSD") - print(info.point, info.digits, info.stops_level, info.freeze_level, info.volume_min, info.volume_step) - ``` -- `volume` must respect broker `volume_min`/`volume_step`. - ---- +Architecture and decisions: [docs/architecture.md](docs/architecture.md), +[docs/adr](docs/adr). ## License -CC-BY-NC 4.0 - - - - - - - +[CC BY-NC 4.0](LICENSE). Trading carries risk; this software comes without any +warranty. diff --git a/docs/adr/0001-ports-only-at-process-boundaries.md b/docs/adr/0001-ports-only-at-process-boundaries.md new file mode 100644 index 0000000..879fd09 --- /dev/null +++ b/docs/adr/0001-ports-only-at-process-boundaries.md @@ -0,0 +1,24 @@ +# ADR 0001: Ports only at process boundaries + +- Status: accepted (3.0.0) + +## Context + +2.x called `MetaTrader5` functions from one 535-line class, so every rule +(price rounding, stop maths, retry decisions) needed a live terminal to test. + +## Decision + +Two ports, `Terminal` and `Clock`, one per process boundary. Everything that +does no I/O is a plain function or a method on a domain object. + +We chose one port per boundary over one port per concern (e.g. separate +`PriceFeed` and `OrderGateway`). Both concerns go over the same IPC channel to +one terminal process. Splitting them would let tests fake an impossible state +(quotes from one terminal, orders sent to another) and would hide that a single +`shutdown()` ends both. + +## Consequences + +- Unit tests run on any OS against `FakeTerminal`. +- The MT5 adapter is the only module that knows MT5 request dictionaries. diff --git a/docs/adr/0002-result-at-boundaries.md b/docs/adr/0002-result-at-boundaries.md new file mode 100644 index 0000000..394c610 --- /dev/null +++ b/docs/adr/0002-result-at-boundaries.md @@ -0,0 +1,25 @@ +# ADR 0002: Result values at boundaries, exceptions for programming errors + +- Status: accepted (3.0.0) + +## Context + +Most trading failures are expected (market closed, no money, requote). 2.x +mixed `None`, `False`, raw MT5 results and endless loops. + +## Decision + +Use cases and ports return `Ok(value)` or `Err(error)`. `TradeError` carries an +`ErrorKind`, the retcode and the broker's receipt. Batch operations return a +`BatchFailure` with the outcome of each ticket. Exceptions are raised only for +programming errors, such as an invalid `RetryPolicy`. + +We chose a small in-house `Result` over the `returns` library because that +library would add a runtime dependency and a mypy plugin to every user's +project for the sake of two dataclasses. We chose it over exceptions because +an unhandled `MarketClosedError` in a webhook handler silently drops the signal. + +## Consequences + +- Callers have to look at the outcome; `match` statements read naturally. +- A batch close never reports "done" while some positions are still open. diff --git a/docs/adr/0003-bounded-retries.md b/docs/adr/0003-bounded-retries.md new file mode 100644 index 0000000..0b872dc --- /dev/null +++ b/docs/adr/0003-bounded-retries.md @@ -0,0 +1,25 @@ +# ADR 0003: Bounded retries, never on an unknown outcome + +- Status: accepted (3.0.0) + +## Context + +2.x retried every unknown retcode forever, 0.5 s apart. A bot that hit +NO_MONEY or MARKET_CLOSED blocked indefinitely and kept sending orders. + +## Decision + +Retry only the codes where the server provably did not execute the request: +REQUOTE (10004), PRICE_CHANGED (10020), PRICE_OFF (10021) and +TOO_MANY_REQUESTS (10024). The default is 3 attempts, 0.5 s apart. Each attempt +rebuilds the request from a fresh quote. An explicit `price` is sent only once. + +TIMEOUT (10012) and CONNECTION (10031) come back as `OUTCOME_UNKNOWN` and are +never retried. We chose "report it and let the caller check positions" over +"retry" because a retry after a request that did reach the server opens a +second position without any error. + +## Consequences + +- Every call returns within `attempts × (delay + round trip)`. +- Callers that handle `OUTCOME_UNKNOWN` must reconcile with `positions()`. diff --git a/docs/adr/0004-no-gui-automation.md b/docs/adr/0004-no-gui-automation.md new file mode 100644 index 0000000..7952ec5 --- /dev/null +++ b/docs/adr/0004-no-gui-automation.md @@ -0,0 +1,22 @@ +# ADR 0004: No GUI automation for Algo Trading + +- Status: accepted (3.0.0) + +## Context + +On retcode 10027 (AutoTrading disabled by the client), 2.x pressed Ctrl+E +through `pyautogui`. + +## Decision + +Return `ALGO_TRADING_DISABLED` with an instruction, and never send keystrokes. + +We chose an explicit error over the hotkey because Ctrl+E *toggles* the +setting (a second call switches it off again). The keystroke also goes to +whichever window has focus, so on a desktop it typed into the user's editor or +browser. + +## Consequences + +- `pyautogui` is no longer a dependency, and the library works headless. +- Users have to enable Algo Trading once in the terminal. diff --git a/docs/adr/0005-stdlib-logging.md b/docs/adr/0005-stdlib-logging.md new file mode 100644 index 0000000..8dfbdd0 --- /dev/null +++ b/docs/adr/0005-stdlib-logging.md @@ -0,0 +1,24 @@ +# ADR 0005: Standard logging, no NullHandler + +- Status: accepted (3.0.0) + +## Context + +2.x logged with `loguru`, which writes to a global sink that the application +does not control. It also logged the full `account_info()`, including the +owner's name and balance. + +## Decision + +Use `logging.getLogger("PythonMetaTrader5")`, configure nothing, and log only +the login and server on connect. + +We chose not to add the customary `NullHandler`. With it, an unconfigured +script swallows every ERROR record, so a failed order would leave no trace. +Without it, Python's last-resort handler still prints warnings and errors to +stderr. + +## Consequences + +- Applications control format and destination with standard tooling. +- 2.x users lose info-level console output unless they configure logging. diff --git a/docs/adr/0006-legacy-facade.md b/docs/adr/0006-legacy-facade.md new file mode 100644 index 0000000..d6dba3e --- /dev/null +++ b/docs/adr/0006-legacy-facade.md @@ -0,0 +1,27 @@ +# ADR 0006: Keep a 2.x `Broker` facade; drop the star re-export + +- Status: accepted (3.0.0) + +## Context + +The package has tens of thousands of downloads, and existing scripts call +`Broker(...)` and its CamelCase methods. 2.x also ran +`from MetaTrader5 import *` in its `__init__`, which re-exported the whole MT5 +namespace. + +## Decision + +`PythonMetaTrader5.Broker` keeps the 2.x names, arguments and return shapes. +It delegates to `Trader` and emits a `DeprecationWarning`. The unsafe 2.x +behaviours are not reproduced (see MIGRATION.md). The star re-export is removed. + +We chose a facade over keeping the 2.x code because the old code is exactly +the code that loops forever. We chose it over removing `Broker` because an +unattended bot upgraded by `pip install -U` would crash at import instead of +running safely. We dropped the re-export because shadowing MT5's namespace made +every new MT5 symbol part of our public API without any review. + +## Consequences + +- Old scripts keep running. Scripts that relied on re-exported MT5 names must + import `MetaTrader5` directly. diff --git a/docs/adr/0007-filling-and-price-grid.md b/docs/adr/0007-filling-and-price-grid.md new file mode 100644 index 0000000..b9a1074 --- /dev/null +++ b/docs/adr/0007-filling-and-price-grid.md @@ -0,0 +1,24 @@ +# ADR 0007: Filling mode from the symbol, prices on the tick grid + +- Status: accepted (3.0.0); to be confirmed on more brokers with the demo tests + +## Context + +2.x sent FOK for entries and IOC for closes regardless of the symbol, and it +rounded prices to `digits`. + +## Decision + +Market orders use the first mode the symbol allows, in the order +FOK > IOC > RETURN. Pending orders use RETURN. Prices snap to +`trade_tick_size` (falling back to `point`) and are then rounded to `digits`. + +We prefer FOK over IOC because IOC can fill only part of the requested volume +and still report success, leaving a bot with a position size it never asked +for. Prices snap to the tick grid because rounding to `digits` produces prices +like 5780.13 on a 0.25-tick index, which the server rejects. + +## Consequences + +- Brokers that do not allow FOK no longer reject every order with 10030. +- A partial IOC fill is still `Ok`; `receipt.volume` gives the filled size. diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..adc0e3b --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,52 @@ +# Architecture + +Clean Architecture with Ports & Adapters. Dependencies point inwards only: + +``` +legacy/ (Broker facade) ─┐ +connection.py (connect) ─┼─► application/ ─► domain/ ─► result.py +adapters/ ───────────────┘ ▲ + (implement the ports) ─────────┘ +``` + +| Layer | Package | Knows about | I/O | +|---|---|---|---| +| Domain | `domain/` | trading rules only: sides, stops, symbol specs, retcode meaning, requests, read models | none | +| Application | `application/` | use cases (`Trader`), retry loop, batch reporting, **ports** | only through ports | +| Adapters | `adapters/` | the `MetaTrader5` package, `time.sleep` | yes | +| Composition | `connection.py` | wires adapters into a `Trader` | through adapters | +| Compatibility | `legacy/` | the 2.x `Broker` API mapped onto `Trader` | through `Trader` and ports | + +## Ports + +There are exactly two, one per process boundary +([ADR 0001](adr/0001-ports-only-at-process-boundaries.md)): + +- `Terminal`: the MetaTrader 5 terminal (IPC to `terminal64.exe`). +- `Clock`: waiting between retries. + +Pure logic (price normalisation, stop resolution, retcode classification, +volume checks) is plain functions and methods on domain objects, not ports. + +## Request flow: `open_position` + +1. Validate side, comment, symbol spec and volume. Errors return before any + order is sent. +2. Build the request from the **current** quote (`Tick.entry_price`), resolving + `Stop.points` against that price. +3. `execute()` sends it and classifies the retcode + ([ADR 0003](adr/0003-bounded-retries.md)): success → `Ok`; retryable → + sleep and rebuild with a fresh quote; anything else → `Err` with the receipt. + +## Errors + +Expected failures travel as `Result` values +([ADR 0002](adr/0002-result-at-boundaries.md)). Exceptions are reserved for +programming errors (e.g. `RetryPolicy(attempts=0)`). + +## Testing + +- `tests/unit`: fakes for both ports (`fakes.py`) and for the `MetaTrader5` + module (`fake_mt5.py`); runs on any OS. +- `tests/integration`: a real terminal on a demo account, opt-in via `MT5_*`. +- CI also builds the adapter against the real `MetaTrader5` wheel on Windows. From a5a03d4d7e6b7d3ea633dd0fb255baa5bfac9b57 Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 02:12:09 +0100 Subject: [PATCH 07/28] fix: close review findings on symbol filters, unknown outcomes and fills All found by /code-review high on this branch, each reproduced by a failing test first (tests/unit/test_safety_edges.py). - An empty symbol is rejected: MT5 treats a falsy filter as all symbols, so close_positions("") would have closed the whole account. The adapter now forwards "" as a filter instead of dropping it. - Broker.Close(None) without a ticket closes nothing, as 2.x did. - order_send returning None is OUTCOME_UNKNOWN unless last_error proves the request never left the process; a plain TERMINAL_ERROR invited a re-send. - symbol_select failure is an error; a missing first quote is retried since nothing was sent yet. - DONE_PARTIAL on a close is a PARTIAL_FILL error. - Pending orders use the symbol filling mode: a fixed RETURN is refused by market-execution brokers, where the 2.x IOC was accepted. - connect() maps any unusable login to INVALID_ARGUMENT and shuts the terminal down after a failed login. - close-all reads each symbol spec once; closes use Tick.exit_price. - SymbolSpec.stops_level removed: unused, and a local check would be wrong for brokers with floating stop levels (stops_level 0). --- CHANGELOG.md | 7 + MIGRATION.md | 2 + README.md | 5 +- docs/adr/0003-bounded-retries.md | 13 ++ docs/adr/0007-filling-and-price-grid.md | 11 +- .../adapters/mt5_terminal.py | 33 +++- .../application/execution.py | 5 + src/PythonMetaTrader5/application/trader.py | 71 ++++++--- src/PythonMetaTrader5/connection.py | 5 +- src/PythonMetaTrader5/domain/errors.py | 2 + src/PythonMetaTrader5/domain/retcodes.py | 3 +- src/PythonMetaTrader5/domain/symbol.py | 1 - src/PythonMetaTrader5/legacy/broker.py | 4 + tests/unit/fakes.py | 7 + tests/unit/test_mt5_adapter.py | 2 +- tests/unit/test_pending_orders.py | 2 +- tests/unit/test_safety_edges.py | 150 ++++++++++++++++++ 17 files changed, 284 insertions(+), 39 deletions(-) create mode 100644 tests/unit/test_safety_edges.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 78c3b16..6f792fa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -35,6 +35,13 @@ Complete rewrite. See [MIGRATION.md](MIGRATION.md) for every behaviour change. - The `from MetaTrader5 import *` re-export. - The `Broker.password` attribute. +### Safety +- An empty symbol (`""`) is rejected instead of meaning "every symbol". +- `order_send` failures that may have reached the server are reported as + `OUTCOME_UNKNOWN`, never as a plain terminal error. +- A partly filled close is a `PARTIAL_FILL` error. +- A failed login shuts the terminal session down. + ### Fixed - `Close(ticket=...)` with `symbol=None` crashed. - `CancelOrders` and `Close` could loop forever. diff --git a/MIGRATION.md b/MIGRATION.md index 51b173b..82531ba 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -17,6 +17,8 @@ upgrading a bot that trades real money. | On retcode 10027 it pressed **Ctrl+E** via `pyautogui` | Logs "enable Algo Trading" and returns the receipt | Ctrl+E *toggles* Algo Trading and is typed into whichever window has focus | | `Close()` always returned `False` | `True` if at least one position closed and none failed, else `False` | The return value was meaningless | | `Close(symbol=None, ticket=...)` crashed | Each position is closed on its own symbol | It priced the close with the `symbol` argument | +| `Close(None)` without a ticket crashed without closing anything | Still closes nothing: logs an error, returns `False` | Forwarding `None` would close every position on the account | +| A partly filled close counted as closed | Reported as a failure (`PARTIAL_FILL`), `Close()` returns `False` | The rest of the position was left open silently | | `CancelOrders` could loop forever on a failed cancel | One attempt per order (requotes retried), failures logged | Same as above | | Comments longer than 31 characters made `order_send` fail with `None` | Rejected before sending, logged | Explicit error instead of a crash downstream | | `ticket=` on `OpenPosition`/`Buy`/`Sell`/`BuyLimit`/`SellLimit` was forwarded as `position` | Refused: returns `None`, logs an error | On hedging accounts it turned an entry into a close of that position | diff --git a/README.md b/README.md index 7ff616e..fcd4dff 100644 --- a/README.md +++ b/README.md @@ -93,9 +93,10 @@ deviation=10, retry=None) -> Result[Trader, TradeError]` | Server answer | What happens | |---|---| -| done, placed, partial fill | `Ok(receipt)` | +| done, placed, partial fill on an entry | `Ok(receipt)` (`receipt.volume` is the filled size) | +| partial fill on a close | `PARTIAL_FILL`: the rest of the position is still open | | requote, price changed, no quotes, too many requests | retried with a fresh quote, up to `RetryPolicy.attempts` (default 3, 0.5 s apart), then `RETRIES_EXHAUSTED` | -| timeout, no connection | `OUTCOME_UNKNOWN`, never retried: check `positions()` first | +| timeout, no connection, or `order_send` lost in IPC | `OUTCOME_UNKNOWN`, never retried: check `positions()` first | | anything else | the matching `ErrorKind`, returned at once | ```python diff --git a/docs/adr/0003-bounded-retries.md b/docs/adr/0003-bounded-retries.md index 0b872dc..deb4b98 100644 --- a/docs/adr/0003-bounded-retries.md +++ b/docs/adr/0003-bounded-retries.md @@ -19,6 +19,19 @@ never retried. We chose "report it and let the caller check positions" over "retry" because a retry after a request that did reach the server opens a second position without any error. +The same rule applies when `order_send` itself returns `None`. Only the +`last_error()` codes that prove the request never left the process (invalid +arguments, no IPC link, terminal refused) become `TERMINAL_ERROR`. Send, +receive and IPC-timeout failures become `OUTCOME_UNKNOWN`. + +A missing quote while the request is being built (`NO_PRICE`) is retried, +because nothing has been sent yet. A symbol that was just added to Market Watch +has no quote for a moment. + +A partial fill (`DONE_PARTIAL`) on a close is an error (`PARTIAL_FILL`): the +rest of the position is still open. On an entry it stays `Ok`, and +`receipt.volume` gives the filled size. + ## Consequences - Every call returns within `attempts × (delay + round trip)`. diff --git a/docs/adr/0007-filling-and-price-grid.md b/docs/adr/0007-filling-and-price-grid.md index b9a1074..99ccb7a 100644 --- a/docs/adr/0007-filling-and-price-grid.md +++ b/docs/adr/0007-filling-and-price-grid.md @@ -9,9 +9,14 @@ rounded prices to `digits`. ## Decision -Market orders use the first mode the symbol allows, in the order -FOK > IOC > RETURN. Pending orders use RETURN. Prices snap to -`trade_tick_size` (falling back to `point`) and are then rounded to `digits`. +Market and pending orders use the first mode the symbol allows, in the order +FOK > IOC > RETURN. Prices snap to `trade_tick_size` (falling back to `point`) +and are then rounded to `digits`. + +An earlier draft used a fixed RETURN for pending orders. We dropped it because +MQL5 documents RETURN as not allowed in Market execution mode, so on those +brokers every limit order would have been refused with 10030, while the IOC +that 2.x sent was accepted. We prefer FOK over IOC because IOC can fill only part of the requested volume and still report success, leaving a bot with a position size it never asked diff --git a/src/PythonMetaTrader5/adapters/mt5_terminal.py b/src/PythonMetaTrader5/adapters/mt5_terminal.py index fab7a81..d84bf3c 100644 --- a/src/PythonMetaTrader5/adapters/mt5_terminal.py +++ b/src/PythonMetaTrader5/adapters/mt5_terminal.py @@ -26,6 +26,11 @@ # MT5 reports "nothing found" and "call failed" both as None; only last_error() # tells them apart. 1 is RES_S_OK. _RES_S_OK = 1 +# last_error() codes for which order_send provably never left this process +# (bad arguments, no IPC link, terminal refused). Any other failure (send, +# receive, timeout) may have reached the server, so its outcome is unknown. +_NOT_SENT = frozenset({-2, -3, -4, -5, -6, -7, -10003, -10004}) +_AUTO_TRADING_DISABLED = -8 class MetaTrader5Terminal: @@ -81,9 +86,14 @@ def symbol(self, name: str) -> Result[SymbolSpec, TradeError]: info = self._mt5.symbol_info(name) if info is None: return Err(TradeError(ErrorKind.SYMBOL_NOT_FOUND, f"unknown symbol {name!r}")) - if not info.visible: - # Hidden symbols have no quotes; 2.x left users to fix Market Watch by hand. - self._mt5.symbol_select(name, True) + # Hidden symbols have no quotes; 2.x left users to fix Market Watch by hand. + if not info.visible and not self._mt5.symbol_select(name, True): + return Err( + TradeError( + ErrorKind.SYMBOL_NOT_FOUND, + f"{name!r} cannot be added to Market Watch: {self._last_error()}", + ) + ) return Ok( SymbolSpec( name=info.name, @@ -94,7 +104,6 @@ def symbol(self, name: str) -> Result[SymbolSpec, TradeError]: volume_max=float(info.volume_max), volume_step=float(info.volume_step), filling_flags=int(info.filling_mode), - stops_level=int(info.trade_stops_level), ) ) @@ -110,7 +119,7 @@ def send(self, request: OrderRequest | CancelRequest) -> Result[TradeReceipt, Tr result = self._mt5.order_send(payload) if result is None: return Err( - TradeError(ErrorKind.TERMINAL_ERROR, f"order_send failed: {self._last_error()}") + TradeError(self._send_failure_kind(), f"order_send failed: {self._last_error()}") ) return Ok( TradeReceipt( @@ -129,7 +138,11 @@ def send(self, request: OrderRequest | CancelRequest) -> Result[TradeReceipt, Tr def positions( self, *, symbol: str | None = None, ticket: int | None = None ) -> Result[list[Position], TradeError]: - query = {"ticket": ticket} if ticket is not None else {"symbol": symbol} if symbol else {} + query: dict[str, object] = {} + if ticket is not None: + query["ticket"] = ticket + elif symbol is not None: + query["symbol"] = symbol raw = self._listing(self._mt5.positions_get(**query), "positions_get") if isinstance(raw, Err): return raw @@ -138,7 +151,7 @@ def positions( def pending_orders( self, *, symbol: str | None = None ) -> Result[list[PendingOrder], TradeError]: - query = {"symbol": symbol} if symbol else {} + query = {"symbol": symbol} if symbol is not None else {} raw = self._listing(self._mt5.orders_get(**query), "orders_get") if isinstance(raw, Err): return raw @@ -212,6 +225,12 @@ def _listing(self, raw: Any, call: str) -> Result[tuple[Any, ...], TradeError]: return Ok(()) return Err(TradeError(ErrorKind.TERMINAL_ERROR, f"{call} failed: {self._last_error()}")) + def _send_failure_kind(self) -> ErrorKind: + code, _ = self._mt5.last_error() + if code == _AUTO_TRADING_DISABLED: + return ErrorKind.ALGO_TRADING_DISABLED + return ErrorKind.TERMINAL_ERROR if code in _NOT_SENT else ErrorKind.OUTCOME_UNKNOWN + def _last_error(self) -> str: code, message = self._mt5.last_error() return f"[{code}] {message}" diff --git a/src/PythonMetaTrader5/application/execution.py b/src/PythonMetaTrader5/application/execution.py index 71fdf7b..40de72b 100644 --- a/src/PythonMetaTrader5/application/execution.py +++ b/src/PythonMetaTrader5/application/execution.py @@ -42,6 +42,11 @@ def execute( for attempt in range(1, policy.attempts + 1): request = build() if isinstance(request, Err): + # Nothing was sent, so waiting is safe; a symbol just added to Market + # Watch typically has no quote for the first few hundred milliseconds. + if request.error.kind is ErrorKind.NO_PRICE and attempt < policy.attempts: + clock.sleep(policy.delay_seconds) + continue return request sent = terminal.send(request.value) if isinstance(sent, Err): diff --git a/src/PythonMetaTrader5/application/trader.py b/src/PythonMetaTrader5/application/trader.py index a699065..8fd621d 100644 --- a/src/PythonMetaTrader5/application/trader.py +++ b/src/PythonMetaTrader5/application/trader.py @@ -8,12 +8,13 @@ from PythonMetaTrader5.application.batch import BatchFailure, run_batch, with_magic from PythonMetaTrader5.application.execution import RetryPolicy, execute from PythonMetaTrader5.application.ports import Clock, Terminal -from PythonMetaTrader5.domain.errors import TradeError +from PythonMetaTrader5.domain.errors import ErrorKind, TradeError from PythonMetaTrader5.domain.market import PendingKind, PendingOrder, Position, TradeReceipt from PythonMetaTrader5.domain.orders import Side, validate_comment from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest +from PythonMetaTrader5.domain.retcodes import DONE_PARTIAL from PythonMetaTrader5.domain.stops import Stop -from PythonMetaTrader5.domain.symbol import Filling, SymbolSpec +from PythonMetaTrader5.domain.symbol import SymbolSpec from PythonMetaTrader5.result import Err, Ok, Result StopInput = Stop | float | None @@ -77,11 +78,7 @@ def build() -> Result[OrderRequest | CancelRequest, TradeError]: if isinstance(tick, Err): return tick reference = tick.value.entry_price(e.side) - return Ok( - self._entry_request( - e, reference, sl=sl, tp=tp, filling=e.spec.market_filling(), pending=None - ) - ) + return Ok(self._entry_request(e, reference, sl=sl, tp=tp, pending=None)) policy = self._retry if price is None else replace(self._retry, attempts=1) return execute(self._terminal, self._clock, build, policy) @@ -107,11 +104,7 @@ def place_limit_order( return entry e = entry.value level = e.spec.normalize_price(price) - # RETURN: a resting order must keep its unfilled remainder; FOK/IOC would - # cancel it the moment it is not immediately fillable. - request = self._entry_request( - e, level, sl=sl, tp=tp, filling=Filling.RETURN, pending=PendingKind.LIMIT - ) + request = self._entry_request(e, level, sl=sl, tp=tp, pending=PendingKind.LIMIT) return execute(self._terminal, self._clock, lambda: Ok(request), self._retry) # ------------------------------------------------------------------- exits @@ -131,7 +124,15 @@ def close_positions( listed = self.positions(None if ticket is not None else symbol, ticket=ticket, magic=magic) if isinstance(listed, Err): return Err(BatchFailure((), (listed.error,))) - return run_batch(listed.value, lambda p: self._close_one(p, text.value)) + # One spec lookup per symbol, not per position: close-all is time-critical. + specs: dict[str, Result[SymbolSpec, TradeError]] = {} + + def close(position: Position) -> Result[TradeReceipt, TradeError]: + if position.symbol not in specs: + specs[position.symbol] = self._terminal.symbol(position.symbol) + return self._close_one(position, specs[position.symbol], text.value) + + return run_batch(listed.value, close) def cancel_pending_orders( self, @@ -150,6 +151,9 @@ def cancel_pending_orders( def positions( self, symbol: str | None = None, *, ticket: int | None = None, magic: int | None = None ) -> Result[list[Position], TradeError]: + invalid = _reject_empty(symbol) + if invalid is not None: + return invalid listed = self._terminal.positions(symbol=symbol, ticket=ticket) return listed if isinstance(listed, Err) else Ok(with_magic(listed.value, magic)) @@ -160,6 +164,9 @@ def pending_orders( magic: int | None = None, kind: PendingKind | None = None, ) -> Result[list[PendingOrder], TradeError]: + invalid = _reject_empty(symbol) + if invalid is not None: + return invalid listed = self._terminal.pending_orders(symbol=symbol) if isinstance(listed, Err): return listed @@ -206,7 +213,6 @@ def _entry_request( *, sl: StopInput, tp: StopInput, - filling: Filling, pending: PendingKind | None, ) -> OrderRequest: stop_loss, take_profit = _as_stop(sl), _as_stop(tp) @@ -215,7 +221,9 @@ def _entry_request( side=e.side, volume=e.volume, price=reference, - filling=filling, + # The symbol's own allowed mode for limits too: a fixed RETURN is refused + # (10030) by market-execution brokers, where the IOC of 2.x was accepted. + filling=e.spec.market_filling(), deviation=self._deviation, magic=self._magic, comment=e.comment, @@ -224,11 +232,12 @@ def _entry_request( pending=pending, ) - def _close_one(self, position: Position, comment: str) -> Result[TradeReceipt, TradeError]: - spec = self._terminal.symbol(position.symbol) + def _close_one( + self, position: Position, spec: Result[SymbolSpec, TradeError], comment: str + ) -> Result[TradeReceipt, TradeError]: if isinstance(spec, Err): return spec - side = position.side.opposite + filling = spec.value.market_filling() def build() -> Result[OrderRequest | CancelRequest, TradeError]: tick = self._terminal.tick(position.symbol) @@ -237,10 +246,10 @@ def build() -> Result[OrderRequest | CancelRequest, TradeError]: return Ok( OrderRequest( symbol=position.symbol, - side=side, + side=position.side.opposite, volume=position.volume, - price=tick.value.entry_price(side), - filling=spec.value.market_filling(), + price=tick.value.exit_price(position.side), + filling=filling, deviation=self._deviation, magic=self._magic, comment=comment, @@ -248,13 +257,31 @@ def build() -> Result[OrderRequest | CancelRequest, TradeError]: ) ) - return execute(self._terminal, self._clock, build, self._retry) + closed = execute(self._terminal, self._clock, build, self._retry) + if isinstance(closed, Ok) and closed.value.retcode == DONE_PARTIAL: + return Err( + TradeError( + ErrorKind.PARTIAL_FILL, + f"closed {closed.value.volume} of {position.volume} lots", + retcode=DONE_PARTIAL, + receipt=closed.value, + ) + ) + return closed def _cancel_one(self, order: PendingOrder) -> Result[TradeReceipt, TradeError]: request = CancelRequest(order=order.ticket) return execute(self._terminal, self._clock, lambda: Ok(request), self._retry) +def _reject_empty(symbol: str | None) -> Err[TradeError] | None: + # "" must not reach the terminal: MT5 treats a falsy filter as "all symbols", + # so a webhook with a missing field would close the whole account. + if symbol == "": + return Err(TradeError(ErrorKind.INVALID_ARGUMENT, "symbol must not be empty")) + return None + + def _as_stop(value: StopInput) -> Stop | None: if value is None or isinstance(value, Stop): return value diff --git a/src/PythonMetaTrader5/connection.py b/src/PythonMetaTrader5/connection.py index ef1ca46..b609feb 100644 --- a/src/PythonMetaTrader5/connection.py +++ b/src/PythonMetaTrader5/connection.py @@ -29,7 +29,7 @@ def connect( """Start (or attach to) the MT5 terminal, log in, and return a ready Trader.""" try: account = int(login) - except ValueError: + except (TypeError, ValueError, OverflowError): return Err(TradeError(ErrorKind.INVALID_ARGUMENT, f"login must be numeric, got {login!r}")) loaded = MetaTrader5Terminal.load() if isinstance(loaded, Err): @@ -38,6 +38,9 @@ def connect( credentials = Credentials(account, str(password), str(server), path, timeout_ms) connected = terminal.connect(credentials) if isinstance(connected, Err): + # initialize() may have attached to (or launched) the terminal before the + # login failed; leaving that IPC session open blocks the next connect(). + terminal.shutdown() return connected # Login and server only: account_info() also carries the owner's name and # balance, which do not belong in application logs. diff --git a/src/PythonMetaTrader5/domain/errors.py b/src/PythonMetaTrader5/domain/errors.py index 68063c7..166da51 100644 --- a/src/PythonMetaTrader5/domain/errors.py +++ b/src/PythonMetaTrader5/domain/errors.py @@ -21,6 +21,8 @@ class ErrorKind(Enum): TRADE_DISABLED = "trade_disabled" ALGO_TRADING_DISABLED = "algo_trading_disabled" LIMIT_REACHED = "limit_reached" + # Only part of the volume was executed; the rest is still open/unfilled. + PARTIAL_FILL = "partial_fill" # The request may or may not have reached the trade server: never auto-retried. OUTCOME_UNKNOWN = "outcome_unknown" RETRIES_EXHAUSTED = "retries_exhausted" diff --git a/src/PythonMetaTrader5/domain/retcodes.py b/src/PythonMetaTrader5/domain/retcodes.py index a3611df..7c8fa37 100644 --- a/src/PythonMetaTrader5/domain/retcodes.py +++ b/src/PythonMetaTrader5/domain/retcodes.py @@ -19,7 +19,8 @@ class Outcome(Enum): # PLACED is how the server confirms a pending order; 2.x only accepted DONE and # therefore re-sent limit orders that had already been placed. -_SUCCESS = frozenset({10008, 10009, 10010}) +DONE_PARTIAL = 10010 +_SUCCESS = frozenset({10008, 10009, DONE_PARTIAL}) # Only codes where the server provably did NOT execute the request. TIMEOUT and # CONNECTION are deliberately absent: the order may already be live, and an diff --git a/src/PythonMetaTrader5/domain/symbol.py b/src/PythonMetaTrader5/domain/symbol.py index f38e353..f2cd5fa 100644 --- a/src/PythonMetaTrader5/domain/symbol.py +++ b/src/PythonMetaTrader5/domain/symbol.py @@ -38,7 +38,6 @@ class SymbolSpec: volume_max: float volume_step: float filling_flags: int - stops_level: int = 0 def normalize_price(self, price: float) -> float: # A price must sit on the tick grid, not merely have `digits` decimals: diff --git a/src/PythonMetaTrader5/legacy/broker.py b/src/PythonMetaTrader5/legacy/broker.py index 1f306b4..4fda80e 100644 --- a/src/PythonMetaTrader5/legacy/broker.py +++ b/src/PythonMetaTrader5/legacy/broker.py @@ -174,6 +174,10 @@ def Close( trader = self._ready() if trader is None: return False + if symbol is None and ticket is None: + # 2.x crashed here without closing anything; 3.x would close the account. + log.error("%s: Close needs a symbol or ticket", self.log) + return False result = trader.close_positions(symbol, ticket=ticket, comment=comment) if isinstance(result, Err): log.error("%s: closing %s: %s", self.log, symbol, result.error) diff --git a/tests/unit/fakes.py b/tests/unit/fakes.py index 9aef8c3..0733772 100644 --- a/tests/unit/fakes.py +++ b/tests/unit/fakes.py @@ -61,6 +61,9 @@ class FakeTerminal: connect_failure: TradeError | None = None sent: list[OrderRequest | CancelRequest] = field(default_factory=list) connected_with: list[Credentials] = field(default_factory=list) + symbol_lookups: list[str] = field(default_factory=list) + # Number of tick() calls answered with NO_PRICE before quotes arrive. + missing_quotes: int = 0 shut_down: bool = False def quote(self, symbol: str, *ticks: tuple[float, float]) -> None: @@ -74,12 +77,16 @@ def shutdown(self) -> None: self.shut_down = True def symbol(self, name: str) -> Result[SymbolSpec, TradeError]: + self.symbol_lookups.append(name) if name not in self.specs: return Err(TradeError(ErrorKind.SYMBOL_NOT_FOUND, name)) return Ok(self.specs[name]) def tick(self, name: str) -> Result[Tick, TradeError]: queue = self.ticks.get(name) + if self.missing_quotes: + self.missing_quotes -= 1 + return Err(TradeError(ErrorKind.NO_PRICE, name)) if not queue: return Err(TradeError(ErrorKind.NO_PRICE, name)) # The last quote sticks, earlier ones are consumed one per call. diff --git a/tests/unit/test_mt5_adapter.py b/tests/unit/test_mt5_adapter.py index 02e21ff..c9b8be4 100644 --- a/tests/unit/test_mt5_adapter.py +++ b/tests/unit/test_mt5_adapter.py @@ -60,7 +60,7 @@ def test_symbol_is_mapped_and_hidden_symbols_are_selected( mt5.symbols["EURUSD"] = symbol_info(visible=False) result = adapter.symbol("EURUSD") assert isinstance(result, Ok) - assert (result.value.digits, result.value.tick_size, result.value.stops_level) == (5, 1e-5, 10) + assert (result.value.digits, result.value.tick_size) == (5, 1e-5) assert ("symbol_select", ("EURUSD", True), {}) in mt5.calls missing = adapter.symbol("NOPE") assert isinstance(missing, Err) diff --git a/tests/unit/test_pending_orders.py b/tests/unit/test_pending_orders.py index 5c38e4c..e79d93a 100644 --- a/tests/unit/test_pending_orders.py +++ b/tests/unit/test_pending_orders.py @@ -17,7 +17,7 @@ def test_limit_order_is_placed_at_its_level(trader: Trader, terminal: FakeTermin (request,) = terminal.sent assert isinstance(request, OrderRequest) assert (request.pending, request.price, request.sl) == (PendingKind.LIMIT, 1.095, 1.0945) - assert request.filling is Filling.RETURN + assert request.filling is Filling.FOK def test_limit_order_rejected_by_server_is_an_error(trader: Trader, terminal: FakeTerminal) -> None: diff --git a/tests/unit/test_safety_edges.py b/tests/unit/test_safety_edges.py new file mode 100644 index 0000000..444a915 --- /dev/null +++ b/tests/unit/test_safety_edges.py @@ -0,0 +1,150 @@ +"""Edge cases where a mistake would close, duplicate or silently lose trades.""" + +import sys + +import pytest + +from PythonMetaTrader5 import Broker, connect +from PythonMetaTrader5.adapters.mt5_terminal import MetaTrader5Terminal +from PythonMetaTrader5.application.trader import Trader +from PythonMetaTrader5.domain.errors import ErrorKind +from PythonMetaTrader5.domain.market import Position +from PythonMetaTrader5.domain.orders import Side +from PythonMetaTrader5.domain.requests import CancelRequest +from PythonMetaTrader5.domain.symbol import Filling +from PythonMetaTrader5.result import Err, Ok + +from .fake_mt5 import FakeMT5, symbol_info +from .fakes import FakeClock, FakeTerminal + + +def position(ticket: int, volume: float = 0.5) -> Position: + return Position( + ticket=ticket, + symbol="EURUSD", + side=Side.BUY, + volume=volume, + price_open=1.0, + sl=None, + tp=None, + price_current=1.0, + profit=0.0, + time=0, + magic=0, + comment="", + ) + + +def test_empty_symbol_is_rejected_instead_of_meaning_all( + trader: Trader, terminal: FakeTerminal +) -> None: + terminal.open_positions = [position(1)] + for result in ( + trader.close_positions(""), + trader.cancel_pending_orders(""), + ): + assert isinstance(result, Err) + assert result.error.errors[0].kind is ErrorKind.INVALID_ARGUMENT + for query in (trader.positions(""), trader.pending_orders("")): + assert isinstance(query, Err) + assert query.error.kind is ErrorKind.INVALID_ARGUMENT + assert terminal.sent == [] + + +def test_adapter_passes_an_empty_symbol_through_as_a_filter() -> None: + mt5 = FakeMT5() + adapter = MetaTrader5Terminal(mt5) + adapter.positions(symbol="") + adapter.pending_orders(symbol="") + filters = [kwargs for name, _, kwargs in mt5.calls if name in {"positions_get", "orders_get"}] + assert filters == [{"symbol": ""}, {"symbol": ""}] + + +def test_legacy_close_without_symbol_or_ticket_closes_nothing( + terminal: FakeTerminal, caplog: pytest.LogCaptureFixture +) -> None: + terminal.open_positions = [position(1)] + with pytest.warns(DeprecationWarning, match="connect"): + broker = Broker(1, "pw", "Demo", terminal=terminal, clock=FakeClock()) + assert broker.Close(None) is False + assert terminal.sent == [] + assert "symbol or ticket" in caplog.text + + +@pytest.mark.parametrize( + ("code", "kind"), + [ + (-10005, ErrorKind.OUTCOME_UNKNOWN), # IPC timeout: request may be on the server + (-10001, ErrorKind.OUTCOME_UNKNOWN), + (-2, ErrorKind.TERMINAL_ERROR), # invalid arguments: never sent + (-10004, ErrorKind.TERMINAL_ERROR), # no IPC connection: never sent + (-8, ErrorKind.ALGO_TRADING_DISABLED), + ], +) +def test_undelivered_send_is_unknown_unless_provably_not_sent(code: int, kind: ErrorKind) -> None: + mt5 = FakeMT5() + mt5.send_result, mt5.error = None, (code, "x") + result = MetaTrader5Terminal(mt5).send(CancelRequest(order=1)) + assert isinstance(result, Err) + assert result.error.kind is kind + + +def test_symbol_that_cannot_be_selected_is_an_error() -> None: + mt5 = FakeMT5() + mt5.symbols["GBPJPY"] = symbol_info("GBPJPY", visible=False) + mt5.symbol_select = lambda name, enable: False # type: ignore[method-assign] + result = MetaTrader5Terminal(mt5).symbol("GBPJPY") + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.SYMBOL_NOT_FOUND + + +def test_first_missing_quote_after_selection_is_waited_for( + trader: Trader, terminal: FakeTerminal, clock: FakeClock +) -> None: + terminal.ticks.clear() + terminal.missing_quotes = 1 + terminal.quote("EURUSD", (1.1, 1.1001)) + assert isinstance(trader.open_position("EURUSD", "buy", 0.1), Ok) + assert clock.sleeps == [0.5] + assert len(terminal.sent) == 1 + + +def test_partial_close_is_a_failure_but_partial_open_is_not( + trader: Trader, terminal: FakeTerminal +) -> None: + terminal.open_positions = [position(1)] + terminal.retcodes.append(10010) + closed = trader.close_positions("EURUSD") + assert isinstance(closed, Err) + assert closed.error.errors[0].kind is ErrorKind.PARTIAL_FILL + terminal.retcodes.append(10010) + assert isinstance(trader.open_position("EURUSD", "buy", 0.1), Ok) + + +def test_limit_order_uses_a_filling_mode_the_symbol_allows( + trader: Trader, terminal: FakeTerminal +) -> None: + trader.place_limit_order("XAUUSD", "buy", 0.1, 2300.0) + (request,) = terminal.sent + assert request.filling is Filling.IOC # type: ignore[union-attr] + + +def test_close_all_reads_each_symbol_spec_once(trader: Trader, terminal: FakeTerminal) -> None: + terminal.open_positions = [position(1), position(2), position(3)] + assert isinstance(trader.close_positions("EURUSD"), Ok) + assert terminal.symbol_lookups == ["EURUSD"] + + +@pytest.mark.parametrize("login", [None, 1.5e400, "abc", [1]]) +def test_unusable_login_is_an_error_not_an_exception(login: object) -> None: + result = connect(login, "pw", "Demo") # type: ignore[arg-type] + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_ARGUMENT + + +def test_failed_login_releases_the_terminal(monkeypatch: pytest.MonkeyPatch) -> None: + mt5 = FakeMT5() + mt5.initialize_ok = False + monkeypatch.setitem(sys.modules, "MetaTrader5", mt5) + assert isinstance(connect(1, "pw", "Demo"), Err) + assert mt5.calls[-1][0] == "shutdown" From 23eb1c854f43fc3a4392b336d5c4e93ed984a870 Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 02:15:11 +0100 Subject: [PATCH 08/28] refactor(adapter): resolve every MT5 constant at construction The Windows CI job builds the adapter against the real MetaTrader5 wheel; with constants resolved lazily in _payload/_position a renamed TRADE_ACTION_* or ORDER_TIME_GTC would only fail on the first live order. Also states in the README and docstring that close_positions() and cancel_pending_orders() without arguments act on the whole account. --- README.md | 3 +++ src/PythonMetaTrader5/adapters/mt5_terminal.py | 18 +++++++++++------- src/PythonMetaTrader5/application/trader.py | 6 +++++- 3 files changed, 19 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index fcd4dff..26edf2e 100644 --- a/README.md +++ b/README.md @@ -83,6 +83,9 @@ deviation=10, retry=None) -> Result[Trader, TradeError]` - `price` (market orders): send at this price once instead of the live quote. - `comment`: at most 31 characters (the terminal's limit). Longer comments are rejected, not truncated. +- **`close_positions()` and `cancel_pending_orders()` without arguments act on + the whole account**, including manual trades. A bot should always pass its + `magic` (and a symbol); an empty string `""` is rejected. - `BatchFailure.succeeded` / `.errors` tell exactly which tickets closed and which did not; each `TradeError.ticket` names the position/order. diff --git a/src/PythonMetaTrader5/adapters/mt5_terminal.py b/src/PythonMetaTrader5/adapters/mt5_terminal.py index d84bf3c..4fda9bc 100644 --- a/src/PythonMetaTrader5/adapters/mt5_terminal.py +++ b/src/PythonMetaTrader5/adapters/mt5_terminal.py @@ -48,6 +48,13 @@ def __init__(self, mt5: Any) -> None: Filling.IOC: mt5.ORDER_FILLING_IOC, Filling.RETURN: mt5.ORDER_FILLING_RETURN, } + # Every constant is read here, not at first use, so building the adapter + # against a new MetaTrader5 release fails at once if one was renamed. + self._deal = mt5.TRADE_ACTION_DEAL + self._pending = mt5.TRADE_ACTION_PENDING + self._remove = mt5.TRADE_ACTION_REMOVE + self._good_till_cancel = mt5.ORDER_TIME_GTC + self._position_buy = mt5.POSITION_TYPE_BUY @classmethod def load(cls) -> Result[MetaTrader5Terminal, TradeError]: @@ -179,13 +186,10 @@ def pending_orders( # ------------------------------------------------------------------ helpers def _payload(self, request: OrderRequest | CancelRequest) -> dict[str, Any]: - mt5 = self._mt5 if isinstance(request, CancelRequest): - return {"action": mt5.TRADE_ACTION_REMOVE, "order": request.order} + return {"action": self._remove, "order": request.order} payload: dict[str, Any] = { - "action": mt5.TRADE_ACTION_DEAL - if request.pending is None - else mt5.TRADE_ACTION_PENDING, + "action": self._deal if request.pending is None else self._pending, "symbol": request.symbol, "volume": request.volume, "type": self._order_types[(request.side, request.pending)], @@ -194,7 +198,7 @@ def _payload(self, request: OrderRequest | CancelRequest) -> dict[str, Any]: "magic": request.magic, "comment": request.comment, "type_filling": self._fillings[request.filling], - "type_time": mt5.ORDER_TIME_GTC, + "type_time": self._good_till_cancel, } optional = {"sl": request.sl, "tp": request.tp, "position": request.position} payload.update({key: value for key, value in optional.items() if value is not None}) @@ -204,7 +208,7 @@ def _position(self, p: Any) -> Position: return Position( ticket=int(p.ticket), symbol=str(p.symbol), - side=Side.BUY if p.type == self._mt5.POSITION_TYPE_BUY else Side.SELL, + side=Side.BUY if p.type == self._position_buy else Side.SELL, volume=float(p.volume), price_open=float(p.price_open), # MT5 encodes "no stop" as 0.0, which is also a (useless) price. diff --git a/src/PythonMetaTrader5/application/trader.py b/src/PythonMetaTrader5/application/trader.py index 8fd621d..c8850cc 100644 --- a/src/PythonMetaTrader5/application/trader.py +++ b/src/PythonMetaTrader5/application/trader.py @@ -117,7 +117,11 @@ def close_positions( magic: int | None = None, comment: str | None = None, ) -> Result[list[TradeReceipt], BatchFailure]: - """Close matching positions; ``ticket`` takes precedence over ``symbol``.""" + """Close matching positions; ``ticket`` takes precedence over ``symbol``. + + With neither ``symbol``, ``ticket`` nor ``magic`` this closes EVERY position + on the account, manual ones included. Pass ``magic`` to touch only your own. + """ text = validate_comment(comment) if isinstance(text, Err): return Err(BatchFailure((), (text.error,))) From a69f3b99f82fdee3aa0e3522ea41fe5fe94136f6 Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 02:22:58 +0100 Subject: [PATCH 09/28] fix: second review round on fills, sessions, logins and legacy cancels Each finding reproduced by a failing test first (test_safety_edges.py). - Pending orders on exchange-execution symbols use RETURN, the only mode that lets a limit rest in the book; elsewhere the symbol market rule stays. - A close counts as done only on DONE; PLACED is OUTCOME_UNKNOWN and DONE_PARTIAL is PARTIAL_FILL. - The adapter shuts the half-open session down after a failed login, so the Broker.login(ToEffect=True) loop can recover; connect() no longer does it. - Broker.CancelOrders(None) cancels nothing, as 2.x did. - Logins that int() would silently coerce (True, 12345678.9, negatives) are rejected instead of logging into another account. - RES_E_* codes come from the MetaTrader5 module and last_error() is read once per failure. - Unit tests patch MetaTrader5 with a fake (autouse): a new test reached the real initialize() and hung until timeout. - README: one connection per process (the package is a global singleton). Field removal check required by project rules for SymbolSpec.stops_level (removed in a5a03d4), grep over the whole repo: $ grep -rn stops_level --include=*.py --include=*.md --include=*.toml . src/PythonMetaTrader5/domain/retcodes.py:39 (10016 message) -> reworded tests/unit/fake_mt5.py:99 (fake trade_stops_level) -> removed after this commit: no references left. No DB, FKs, triggers or views exist. --- README.md | 4 ++ docs/adr/0007-filling-and-price-grid.md | 8 ++-- .../adapters/mt5_terminal.py | 40 +++++++++++----- src/PythonMetaTrader5/application/trader.py | 32 ++++++------- src/PythonMetaTrader5/connection.py | 26 +++++++--- src/PythonMetaTrader5/domain/retcodes.py | 6 ++- src/PythonMetaTrader5/domain/symbol.py | 8 ++++ src/PythonMetaTrader5/legacy/broker.py | 4 ++ tests/unit/conftest.py | 11 +++++ tests/unit/fake_mt5.py | 12 ++++- tests/unit/test_mt5_adapter.py | 2 +- tests/unit/test_safety_edges.py | 47 ++++++++++++++++++- 12 files changed, 158 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 26edf2e..f33ec99 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,10 @@ Built for bots (webhook executors, signal followers) where a trading call must - **SL/TP as prices or distances in points.** - **2.x compatible.** The old `Broker` class still works (deprecated). +> One connection per process: the official package keeps a single global +> terminal session, so a second `connect()` (or its failed login) affects the +> first. Run one process per account. +> > Requires Windows with a MetaTrader 5 terminal installed (the official > `MetaTrader5` package is Windows-only). Enable **Algo Trading** in the terminal. diff --git a/docs/adr/0007-filling-and-price-grid.md b/docs/adr/0007-filling-and-price-grid.md index 99ccb7a..10e575a 100644 --- a/docs/adr/0007-filling-and-price-grid.md +++ b/docs/adr/0007-filling-and-price-grid.md @@ -9,9 +9,11 @@ rounded prices to `digits`. ## Decision -Market and pending orders use the first mode the symbol allows, in the order -FOK > IOC > RETURN. Prices snap to `trade_tick_size` (falling back to `point`) -and are then rounded to `digits`. +Market orders use the first mode the symbol allows, in the order +FOK > IOC > RETURN. Pending orders follow the same rule, except on +exchange-execution symbols, where they use RETURN: there it is the only mode +that lets a limit order rest in the book. Prices snap to `trade_tick_size` +(falling back to `point`) and are then rounded to `digits`. An earlier draft used a fixed RETURN for pending orders. We dropped it because MQL5 documents RETURN as not allowed in Market execution mode, so on those diff --git a/src/PythonMetaTrader5/adapters/mt5_terminal.py b/src/PythonMetaTrader5/adapters/mt5_terminal.py index 4fda9bc..f276f34 100644 --- a/src/PythonMetaTrader5/adapters/mt5_terminal.py +++ b/src/PythonMetaTrader5/adapters/mt5_terminal.py @@ -29,8 +29,16 @@ # last_error() codes for which order_send provably never left this process # (bad arguments, no IPC link, terminal refused). Any other failure (send, # receive, timeout) may have reached the server, so its outcome is unknown. -_NOT_SENT = frozenset({-2, -3, -4, -5, -6, -7, -10003, -10004}) -_AUTO_TRADING_DISABLED = -8 +_NOT_SENT_CODES = ( + "RES_E_INVALID_PARAMS", + "RES_E_NO_MEMORY", + "RES_E_NOT_FOUND", + "RES_E_INVALID_VERSION", + "RES_E_AUTH_FAILED", + "RES_E_UNSUPPORTED", + "RES_E_INTERNAL_FAIL_INIT", + "RES_E_INTERNAL_FAIL_CONNECT", +) class MetaTrader5Terminal: @@ -55,6 +63,9 @@ def __init__(self, mt5: Any) -> None: self._remove = mt5.TRADE_ACTION_REMOVE self._good_till_cancel = mt5.ORDER_TIME_GTC self._position_buy = mt5.POSITION_TYPE_BUY + self._exchange_execution = mt5.SYMBOL_TRADE_EXECUTION_EXCHANGE + self._not_sent = frozenset(getattr(mt5, name) for name in _NOT_SENT_CODES) + self._auto_trading_disabled = mt5.RES_E_AUTO_TRADING_DISABLED @classmethod def load(cls) -> Result[MetaTrader5Terminal, TradeError]: @@ -79,10 +90,14 @@ def connect(self, credentials: Credentials) -> Result[None, TradeError]: timeout=credentials.timeout_ms, ): return Ok(None) + # initialize() may have attached to (or launched) the terminal before the + # login failed; an open half-session makes every later initialize() fail. + error = self._last_error() + self._mt5.shutdown() return Err( TradeError( ErrorKind.CONNECTION_FAILED, - f"login {credentials.login}@{credentials.server} failed: {self._last_error()}", + f"login {credentials.login}@{credentials.server} failed: {error}", ) ) @@ -111,6 +126,7 @@ def symbol(self, name: str) -> Result[SymbolSpec, TradeError]: volume_max=float(info.volume_max), volume_step=float(info.volume_step), filling_flags=int(info.filling_mode), + exchange_execution=int(info.trade_exemode) == self._exchange_execution, ) ) @@ -125,9 +141,7 @@ def send(self, request: OrderRequest | CancelRequest) -> Result[TradeReceipt, Tr payload = self._payload(request) result = self._mt5.order_send(payload) if result is None: - return Err( - TradeError(self._send_failure_kind(), f"order_send failed: {self._last_error()}") - ) + return Err(self._send_failure()) return Ok( TradeReceipt( retcode=int(result.retcode), @@ -229,11 +243,15 @@ def _listing(self, raw: Any, call: str) -> Result[tuple[Any, ...], TradeError]: return Ok(()) return Err(TradeError(ErrorKind.TERMINAL_ERROR, f"{call} failed: {self._last_error()}")) - def _send_failure_kind(self) -> ErrorKind: - code, _ = self._mt5.last_error() - if code == _AUTO_TRADING_DISABLED: - return ErrorKind.ALGO_TRADING_DISABLED - return ErrorKind.TERMINAL_ERROR if code in _NOT_SENT else ErrorKind.OUTCOME_UNKNOWN + def _send_failure(self) -> TradeError: + code, message = self._mt5.last_error() + if code == self._auto_trading_disabled: + kind = ErrorKind.ALGO_TRADING_DISABLED + elif code in self._not_sent: + kind = ErrorKind.TERMINAL_ERROR + else: + kind = ErrorKind.OUTCOME_UNKNOWN + return TradeError(kind, f"order_send failed: [{code}] {message}") def _last_error(self) -> str: code, message = self._mt5.last_error() diff --git a/src/PythonMetaTrader5/application/trader.py b/src/PythonMetaTrader5/application/trader.py index c8850cc..f82361e 100644 --- a/src/PythonMetaTrader5/application/trader.py +++ b/src/PythonMetaTrader5/application/trader.py @@ -12,7 +12,7 @@ from PythonMetaTrader5.domain.market import PendingKind, PendingOrder, Position, TradeReceipt from PythonMetaTrader5.domain.orders import Side, validate_comment from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest -from PythonMetaTrader5.domain.retcodes import DONE_PARTIAL +from PythonMetaTrader5.domain.retcodes import DONE, DONE_PARTIAL from PythonMetaTrader5.domain.stops import Stop from PythonMetaTrader5.domain.symbol import SymbolSpec from PythonMetaTrader5.result import Err, Ok, Result @@ -225,9 +225,7 @@ def _entry_request( side=e.side, volume=e.volume, price=reference, - # The symbol's own allowed mode for limits too: a fixed RETURN is refused - # (10030) by market-execution brokers, where the IOC of 2.x was accepted. - filling=e.spec.market_filling(), + filling=e.spec.market_filling() if pending is None else e.spec.pending_filling(), deviation=self._deviation, magic=self._magic, comment=e.comment, @@ -262,16 +260,17 @@ def build() -> Result[OrderRequest | CancelRequest, TradeError]: ) closed = execute(self._terminal, self._clock, build, self._retry) - if isinstance(closed, Ok) and closed.value.retcode == DONE_PARTIAL: - return Err( - TradeError( - ErrorKind.PARTIAL_FILL, - f"closed {closed.value.volume} of {position.volume} lots", - retcode=DONE_PARTIAL, - receipt=closed.value, - ) - ) - return closed + # Only DONE proves the position is gone. PARTIAL leaves a remainder open and + # PLACED means the close order is queued, not executed: both must surface. + if isinstance(closed, Err) or closed.value.retcode == DONE: + return closed + receipt = closed.value + kind, message = ( + (ErrorKind.PARTIAL_FILL, f"closed {receipt.volume} of {position.volume} lots") + if receipt.retcode == DONE_PARTIAL + else (ErrorKind.OUTCOME_UNKNOWN, "close order accepted but not executed yet") + ) + return Err(TradeError(kind, message, retcode=receipt.retcode, receipt=receipt)) def _cancel_one(self, order: PendingOrder) -> Result[TradeReceipt, TradeError]: request = CancelRequest(order=order.ticket) @@ -279,8 +278,9 @@ def _cancel_one(self, order: PendingOrder) -> Result[TradeReceipt, TradeError]: def _reject_empty(symbol: str | None) -> Err[TradeError] | None: - # "" must not reach the terminal: MT5 treats a falsy filter as "all symbols", - # so a webhook with a missing field would close the whole account. + # "" is rejected rather than passed on: a missing webhook field arrives as "" + # and is easily mistaken for "no filter" (2.x and the first 3.0 draft both + # dropped falsy filters), which would act on the whole account. if symbol == "": return Err(TradeError(ErrorKind.INVALID_ARGUMENT, "symbol must not be empty")) return None diff --git a/src/PythonMetaTrader5/connection.py b/src/PythonMetaTrader5/connection.py index b609feb..e6f5a30 100644 --- a/src/PythonMetaTrader5/connection.py +++ b/src/PythonMetaTrader5/connection.py @@ -27,10 +27,13 @@ def connect( retry: RetryPolicy | None = None, ) -> Result[Trader, TradeError]: """Start (or attach to) the MT5 terminal, log in, and return a ready Trader.""" - try: - account = int(login) - except (TypeError, ValueError, OverflowError): - return Err(TradeError(ErrorKind.INVALID_ARGUMENT, f"login must be numeric, got {login!r}")) + account = _account_number(login) + if account is None: + return Err( + TradeError( + ErrorKind.INVALID_ARGUMENT, f"login must be a positive integer, got {login!r}" + ) + ) loaded = MetaTrader5Terminal.load() if isinstance(loaded, Err): return loaded @@ -38,11 +41,20 @@ def connect( credentials = Credentials(account, str(password), str(server), path, timeout_ms) connected = terminal.connect(credentials) if isinstance(connected, Err): - # initialize() may have attached to (or launched) the terminal before the - # login failed; leaving that IPC session open blocks the next connect(). - terminal.shutdown() return connected # Login and server only: account_info() also carries the owner's name and # balance, which do not belong in application logs. log.info("connected to %s as %s", server, account) return Ok(Trader(terminal, SystemClock(), magic=magic, deviation=deviation, retry=retry)) + + +def _account_number(login: object) -> int | None: + # Exact types only: int(True) == 1 and int(12345678.9) == 12345678 would log + # into a different account than the caller meant, without any error. + if isinstance(login, str) and login.strip().isdigit(): + number = int(login) + elif type(login) is int: + number = login + else: + return None + return number if number > 0 else None diff --git a/src/PythonMetaTrader5/domain/retcodes.py b/src/PythonMetaTrader5/domain/retcodes.py index 7c8fa37..573a103 100644 --- a/src/PythonMetaTrader5/domain/retcodes.py +++ b/src/PythonMetaTrader5/domain/retcodes.py @@ -19,8 +19,10 @@ class Outcome(Enum): # PLACED is how the server confirms a pending order; 2.x only accepted DONE and # therefore re-sent limit orders that had already been placed. +PLACED = 10008 +DONE = 10009 DONE_PARTIAL = 10010 -_SUCCESS = frozenset({10008, 10009, DONE_PARTIAL}) +_SUCCESS = frozenset({PLACED, DONE, DONE_PARTIAL}) # Only codes where the server provably did NOT execute the request. TIMEOUT and # CONNECTION are deliberately absent: the order may already be live, and an @@ -36,7 +38,7 @@ class Outcome(Enum): 10013: (ErrorKind.INVALID_ARGUMENT, "invalid request"), 10014: (ErrorKind.INVALID_VOLUME, "invalid volume"), 10015: (ErrorKind.INVALID_PRICE, "invalid price"), - 10016: (ErrorKind.INVALID_STOPS, "invalid stops; check symbol stops_level"), + 10016: (ErrorKind.INVALID_STOPS, "invalid stops; too close to the price or wrong side"), 10017: (ErrorKind.TRADE_DISABLED, "trading is disabled"), 10018: (ErrorKind.MARKET_CLOSED, "market is closed"), 10019: (ErrorKind.NO_MONEY, "not enough money"), diff --git a/src/PythonMetaTrader5/domain/symbol.py b/src/PythonMetaTrader5/domain/symbol.py index f2cd5fa..b5eeec1 100644 --- a/src/PythonMetaTrader5/domain/symbol.py +++ b/src/PythonMetaTrader5/domain/symbol.py @@ -38,6 +38,7 @@ class SymbolSpec: volume_max: float volume_step: float filling_flags: int + exchange_execution: bool = False def normalize_price(self, price: float) -> float: # A price must sit on the tick grid, not merely have `digits` decimals: @@ -63,6 +64,13 @@ def market_filling(self) -> Filling: return Filling.IOC return Filling.RETURN + def pending_filling(self) -> Filling: + # Exchange-execution symbols (stocks, futures) only let a limit rest in the + # book with RETURN; FOK/IOC there would cancel it unless instantly fillable. + # Elsewhere the market rule applies: RETURN is refused by many + # market-execution brokers (10030) that accepted the IOC sent by 2.x. + return Filling.RETURN if self.exchange_execution else self.market_filling() + def _volume_error(self, volume: float, reason: str) -> TradeError: return TradeError( ErrorKind.INVALID_VOLUME, diff --git a/src/PythonMetaTrader5/legacy/broker.py b/src/PythonMetaTrader5/legacy/broker.py index 4fda80e..9793937 100644 --- a/src/PythonMetaTrader5/legacy/broker.py +++ b/src/PythonMetaTrader5/legacy/broker.py @@ -190,6 +190,10 @@ def CancelOrders(self, symbol: str) -> None: trader = self._ready() if trader is None: return + if not symbol: + # 2.x matched orders against the symbol and so cancelled nothing here. + log.error("%s: CancelOrders needs a symbol", self.log) + return # 2.x only ever cancelled limit orders; stop orders stay untouched. result = trader.cancel_pending_orders(symbol, kind=PendingKind.LIMIT) if isinstance(result, Err): diff --git a/tests/unit/conftest.py b/tests/unit/conftest.py index 387da29..fb37404 100644 --- a/tests/unit/conftest.py +++ b/tests/unit/conftest.py @@ -1,10 +1,21 @@ +import sys + import pytest from PythonMetaTrader5.application.trader import Trader +from .fake_mt5 import FakeMT5 from .fakes import FakeClock, FakeTerminal +@pytest.fixture(autouse=True) +def no_real_terminal(monkeypatch: pytest.MonkeyPatch) -> FakeMT5: + """Unit tests must never reach a real terminal, even where MetaTrader5 is installed.""" + fake = FakeMT5() + monkeypatch.setitem(sys.modules, "MetaTrader5", fake) + return fake + + @pytest.fixture def terminal() -> FakeTerminal: fake = FakeTerminal() diff --git a/tests/unit/fake_mt5.py b/tests/unit/fake_mt5.py index b8ff009..7044f06 100644 --- a/tests/unit/fake_mt5.py +++ b/tests/unit/fake_mt5.py @@ -23,6 +23,16 @@ "ORDER_TIME_GTC": 0, "POSITION_TYPE_BUY": 0, "POSITION_TYPE_SELL": 1, + "SYMBOL_TRADE_EXECUTION_EXCHANGE": 3, + "RES_E_INVALID_PARAMS": -2, + "RES_E_NO_MEMORY": -3, + "RES_E_NOT_FOUND": -4, + "RES_E_INVALID_VERSION": -5, + "RES_E_AUTH_FAILED": -6, + "RES_E_UNSUPPORTED": -7, + "RES_E_AUTO_TRADING_DISABLED": -8, + "RES_E_INTERNAL_FAIL_INIT": -10003, + "RES_E_INTERNAL_FAIL_CONNECT": -10004, } @@ -96,7 +106,7 @@ def symbol_info(name: str = "EURUSD", visible: bool = True) -> SimpleNamespace: volume_max=100.0, volume_step=0.01, filling_mode=1, - trade_stops_level=10, + trade_exemode=2, ) diff --git a/tests/unit/test_mt5_adapter.py b/tests/unit/test_mt5_adapter.py index c9b8be4..8109a18 100644 --- a/tests/unit/test_mt5_adapter.py +++ b/tests/unit/test_mt5_adapter.py @@ -47,7 +47,7 @@ def test_connect_passes_credentials_and_reports_failure( assert result.error.kind is ErrorKind.CONNECTION_FAILED assert "Authorization failed" in result.error.message assert "p" not in result.error.message.split() - assert mt5.calls[-1][1] == ("C:/mt5/terminal64.exe",) + assert mt5.calls[-2][1] == ("C:/mt5/terminal64.exe",) def test_password_never_appears_in_repr() -> None: diff --git a/tests/unit/test_safety_edges.py b/tests/unit/test_safety_edges.py index 444a915..84975d6 100644 --- a/tests/unit/test_safety_edges.py +++ b/tests/unit/test_safety_edges.py @@ -1,14 +1,16 @@ """Edge cases where a mistake would close, duplicate or silently lose trades.""" import sys +from dataclasses import replace import pytest from PythonMetaTrader5 import Broker, connect from PythonMetaTrader5.adapters.mt5_terminal import MetaTrader5Terminal +from PythonMetaTrader5.application.ports import Credentials from PythonMetaTrader5.application.trader import Trader from PythonMetaTrader5.domain.errors import ErrorKind -from PythonMetaTrader5.domain.market import Position +from PythonMetaTrader5.domain.market import PendingKind, PendingOrder, Position from PythonMetaTrader5.domain.orders import Side from PythonMetaTrader5.domain.requests import CancelRequest from PythonMetaTrader5.domain.symbol import Filling @@ -148,3 +150,46 @@ def test_failed_login_releases_the_terminal(monkeypatch: pytest.MonkeyPatch) -> monkeypatch.setitem(sys.modules, "MetaTrader5", mt5) assert isinstance(connect(1, "pw", "Demo"), Err) assert mt5.calls[-1][0] == "shutdown" + + +def test_limit_on_an_exchange_symbol_rests_with_return_filling( + trader: Trader, terminal: FakeTerminal +) -> None: + terminal.specs["EURUSD"] = replace(terminal.specs["EURUSD"], exchange_execution=True) + trader.place_limit_order("EURUSD", "buy", 0.1, 1.05) + trader.open_position("EURUSD", "buy", 0.1) + limit, market = terminal.sent + assert limit.filling is Filling.RETURN # type: ignore[union-attr] + assert market.filling is Filling.FOK # type: ignore[union-attr] + + +def test_close_answered_with_placed_is_not_reported_as_closed( + trader: Trader, terminal: FakeTerminal +) -> None: + terminal.open_positions = [position(1)] + terminal.retcodes.append(10008) + result = trader.close_positions("EURUSD") + assert isinstance(result, Err) + assert result.error.errors[0].kind is ErrorKind.OUTCOME_UNKNOWN + + +def test_legacy_cancel_orders_without_symbol_cancels_nothing(terminal: FakeTerminal) -> None: + terminal.open_orders = [PendingOrder(5, "EURUSD", Side.BUY, PendingKind.LIMIT, 0.1, 1.0, 0, "")] + with pytest.warns(DeprecationWarning, match="connect"): + broker = Broker(1, "pw", "Demo", terminal=terminal, clock=FakeClock()) + broker.CancelOrders(None) # type: ignore[arg-type] + assert terminal.sent == [] + + +@pytest.mark.parametrize("login", [True, 12345678.9, "12 34", -5]) +def test_login_that_would_be_coerced_is_rejected(login: object) -> None: + result = connect(login, "pw", "Demo") # type: ignore[arg-type] + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_ARGUMENT + + +def test_adapter_releases_the_session_after_a_failed_login() -> None: + mt5 = FakeMT5() + mt5.initialize_ok = False + assert isinstance(MetaTrader5Terminal(mt5).connect(Credentials(1, "pw", "s")), Err) + assert [name for name, _, _ in mt5.calls] == ["initialize", "shutdown"] From f5c083340304aa4618a8c4cba56ea0069b141ca3 Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 02:27:07 +0100 Subject: [PATCH 10/28] fix: confirm market deals only on DONE, one login rule, keep live sessions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Third review round; each finding reproduced by a failing test first (tests/unit/test_confirmation.py). - execute() confirms every market deal (entry and close) only on DONE. DONE_PARTIAL is PARTIAL_FILL and PLACED is OUTCOME_UNKNOWN, both with the receipt and never re-sent. The close-only special case is gone. Returning Ok for a partial entry let a bot believe it held 1 lot while holding 0.3. - parse_login() is shared by connect() and Broker: ASCII digits or an int-like value via operator.index, so numpy ints still work while True, floats and non-ASCII digits (int("١") == 1) are rejected. - A failed re-login no longer shuts down a session this adapter opened; MT5 keeps one session per process, so that killed a working connection. - SymbolSpec.exchange_execution is required: a default would quietly treat an exchange symbol as market execution. Adapter mapping now has a test. - RES_S_OK read from the module; last_error() formatted in one place. - README, MIGRATION, CHANGELOG and ADR 0003/0007 updated to the new rules. --- CHANGELOG.md | 11 ++- MIGRATION.md | 4 + README.md | 9 +- docs/adr/0003-bounded-retries.md | 9 +- docs/adr/0007-filling-and-price-grid.md | 2 +- .../adapters/mt5_terminal.py | 24 ++++-- .../application/execution.py | 38 ++++++++- src/PythonMetaTrader5/application/ports.py | 21 +++++ src/PythonMetaTrader5/application/trader.py | 14 +-- src/PythonMetaTrader5/connection.py | 16 +--- src/PythonMetaTrader5/domain/symbol.py | 4 +- src/PythonMetaTrader5/legacy/broker.py | 9 +- tests/unit/fake_mt5.py | 1 + tests/unit/fakes.py | 2 + tests/unit/test_confirmation.py | 85 +++++++++++++++++++ tests/unit/test_mt5_adapter.py | 3 +- tests/unit/test_safety_edges.py | 6 +- tests/unit/test_stops.py | 1 + tests/unit/test_symbol.py | 1 + 19 files changed, 205 insertions(+), 55 deletions(-) create mode 100644 tests/unit/test_confirmation.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 6f792fa..21e83ff 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -39,8 +39,15 @@ Complete rewrite. See [MIGRATION.md](MIGRATION.md) for every behaviour change. - An empty symbol (`""`) is rejected instead of meaning "every symbol". - `order_send` failures that may have reached the server are reported as `OUTCOME_UNKNOWN`, never as a plain terminal error. -- A partly filled close is a `PARTIAL_FILL` error. -- A failed login shuts the terminal session down. +- Market deals (entries and closes) succeed only on DONE: a partial fill is a + `PARTIAL_FILL` error, a queued (PLACED) one is `OUTCOME_UNKNOWN`; neither is + re-sent. +- Logins that would be coerced (`True`, `12345678.9`, non-ASCII digits) are + rejected, in `connect()` and in `Broker`. +- A failed first login shuts the half-open terminal session down; a failed + re-login keeps an already working session. +- Pending orders on exchange-execution symbols use RETURN filling. +- `Broker.Close(None)` / `Broker.CancelOrders(None)` act on nothing. ### Fixed - `Close(ticket=...)` with `symbol=None` crashed. diff --git a/MIGRATION.md b/MIGRATION.md index 82531ba..522916c 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -19,6 +19,10 @@ upgrading a bot that trades real money. | `Close(symbol=None, ticket=...)` crashed | Each position is closed on its own symbol | It priced the close with the `symbol` argument | | `Close(None)` without a ticket crashed without closing anything | Still closes nothing: logs an error, returns `False` | Forwarding `None` would close every position on the account | | A partly filled close counted as closed | Reported as a failure (`PARTIAL_FILL`), `Close()` returns `False` | The rest of the position was left open silently | +| A partial or only-queued (PLACED) market entry counted as opened | Logged as an error; the receipt is still returned, so check `receipt.retcode` (10009 = done) | The bot believed it held the full size | +| `CancelOrders(None)` | Cancels nothing and logs an error | Guards against a missing symbol acting on the whole account | +| `Broker(True, ...)` or `Broker(12345678.9, ...)` logged into account 1 / 12345678 | Raises `ValueError` (as a non-numeric login already did) | It traded on a different account than intended | +| Limit orders on exchange-execution symbols used IOC | Use RETURN so they rest in the book | IOC cancelled them unless instantly fillable | | `CancelOrders` could loop forever on a failed cancel | One attempt per order (requotes retried), failures logged | Same as above | | Comments longer than 31 characters made `order_send` fail with `None` | Rejected before sending, logged | Explicit error instead of a crash downstream | | `ticket=` on `OpenPosition`/`Buy`/`Sell`/`BuyLimit`/`SellLimit` was forwarded as `position` | Refused: returns `None`, logs an error | On hedging accounts it turned an entry into a close of that position | diff --git a/README.md b/README.md index f33ec99..c20efe3 100644 --- a/README.md +++ b/README.md @@ -70,6 +70,9 @@ with trader: # shuts the terminal connection down on exit `connect(login, password, server, *, path=None, timeout_ms=60000, magic=0, deviation=10, retry=None) -> Result[Trader, TradeError]` +`login` must be a positive integer or a string of ASCII digits; `True`, +`12345678.9` and similar values are rejected rather than coerced. + | `Trader` method | Returns | |---|---| | `open_position(symbol, side, volume, *, sl=None, tp=None, price=None, comment=None)` | `Result[TradeReceipt, TradeError]` | @@ -100,8 +103,10 @@ deviation=10, retry=None) -> Result[Trader, TradeError]` | Server answer | What happens | |---|---| -| done, placed, partial fill on an entry | `Ok(receipt)` (`receipt.volume` is the filled size) | -| partial fill on a close | `PARTIAL_FILL`: the rest of the position is still open | +| market deal (entry or close): done | `Ok(receipt)` | +| pending order: placed or done | `Ok(receipt)` | +| market deal: partial fill | `PARTIAL_FILL` with the receipt; part of the deal exists, never re-sent | +| market deal: placed (queued, not executed) | `OUTCOME_UNKNOWN` with the receipt, never re-sent | | requote, price changed, no quotes, too many requests | retried with a fresh quote, up to `RetryPolicy.attempts` (default 3, 0.5 s apart), then `RETRIES_EXHAUSTED` | | timeout, no connection, or `order_send` lost in IPC | `OUTCOME_UNKNOWN`, never retried: check `positions()` first | | anything else | the matching `ErrorKind`, returned at once | diff --git a/docs/adr/0003-bounded-retries.md b/docs/adr/0003-bounded-retries.md index deb4b98..43ba095 100644 --- a/docs/adr/0003-bounded-retries.md +++ b/docs/adr/0003-bounded-retries.md @@ -28,9 +28,12 @@ A missing quote while the request is being built (`NO_PRICE`) is retried, because nothing has been sent yet. A symbol that was just added to Market Watch has no quote for a moment. -A partial fill (`DONE_PARTIAL`) on a close is an error (`PARTIAL_FILL`): the -rest of the position is still open. On an entry it stays `Ok`, and -`receipt.volume` gives the filled size. +Only DONE proves that a market deal (an entry or a close) executed in full. +DONE_PARTIAL becomes `PARTIAL_FILL` and PLACED becomes `OUTCOME_UNKNOWN`, both +carrying the receipt and neither retried, because part of the deal may already +exist. An earlier draft returned `Ok` for a partial entry. We dropped that +because a bot asking for 1 lot would believe it held 1 lot while holding 0.3. +For pending orders, PLACED is the normal success. ## Consequences diff --git a/docs/adr/0007-filling-and-price-grid.md b/docs/adr/0007-filling-and-price-grid.md index 10e575a..95dafb3 100644 --- a/docs/adr/0007-filling-and-price-grid.md +++ b/docs/adr/0007-filling-and-price-grid.md @@ -28,4 +28,4 @@ like 5780.13 on a 0.25-tick index, which the server rejects. ## Consequences - Brokers that do not allow FOK no longer reject every order with 10030. -- A partial IOC fill is still `Ok`; `receipt.volume` gives the filled size. +- A partial IOC fill is a `PARTIAL_FILL` error carrying the receipt (see ADR 0003). diff --git a/src/PythonMetaTrader5/adapters/mt5_terminal.py b/src/PythonMetaTrader5/adapters/mt5_terminal.py index f276f34..ed6bb8d 100644 --- a/src/PythonMetaTrader5/adapters/mt5_terminal.py +++ b/src/PythonMetaTrader5/adapters/mt5_terminal.py @@ -25,7 +25,6 @@ # MT5 reports "nothing found" and "call failed" both as None; only last_error() # tells them apart. 1 is RES_S_OK. -_RES_S_OK = 1 # last_error() codes for which order_send provably never left this process # (bad arguments, no IPC link, terminal refused). Any other failure (send, # receive, timeout) may have reached the server, so its outcome is unknown. @@ -66,6 +65,10 @@ def __init__(self, mt5: Any) -> None: self._exchange_execution = mt5.SYMBOL_TRADE_EXECUTION_EXCHANGE self._not_sent = frozenset(getattr(mt5, name) for name in _NOT_SENT_CODES) self._auto_trading_disabled = mt5.RES_E_AUTO_TRADING_DISABLED + self._ok = mt5.RES_S_OK + # MT5 keeps one session per process; it is only ours to close after a + # failed login if no earlier login of this adapter opened it. + self._session_open = False @classmethod def load(cls) -> Result[MetaTrader5Terminal, TradeError]: @@ -89,11 +92,13 @@ def connect(self, credentials: Credentials) -> Result[None, TradeError]: server=credentials.server, timeout=credentials.timeout_ms, ): + self._session_open = True return Ok(None) - # initialize() may have attached to (or launched) the terminal before the - # login failed; an open half-session makes every later initialize() fail. error = self._last_error() - self._mt5.shutdown() + if not self._session_open: + # initialize() may have attached to (or launched) the terminal before + # the login failed; that half-session makes every later attempt fail. + self._mt5.shutdown() return Err( TradeError( ErrorKind.CONNECTION_FAILED, @@ -239,23 +244,26 @@ def _listing(self, raw: Any, call: str) -> Result[tuple[Any, ...], TradeError]: if raw is not None: return Ok(tuple(raw)) code, _ = self._mt5.last_error() - if code == _RES_S_OK: + if code == self._ok: return Ok(()) return Err(TradeError(ErrorKind.TERMINAL_ERROR, f"{call} failed: {self._last_error()}")) def _send_failure(self) -> TradeError: - code, message = self._mt5.last_error() + code, text = self._error() if code == self._auto_trading_disabled: kind = ErrorKind.ALGO_TRADING_DISABLED elif code in self._not_sent: kind = ErrorKind.TERMINAL_ERROR else: kind = ErrorKind.OUTCOME_UNKNOWN - return TradeError(kind, f"order_send failed: [{code}] {message}") + return TradeError(kind, f"order_send failed: {text}") def _last_error(self) -> str: + return self._error()[1] + + def _error(self) -> tuple[int, str]: code, message = self._mt5.last_error() - return f"[{code}] {message}" + return code, f"[{code}] {message}" def _order_type_table(mt5: Any) -> dict[tuple[Side, PendingKind | None], int]: diff --git a/src/PythonMetaTrader5/application/execution.py b/src/PythonMetaTrader5/application/execution.py index 40de72b..6914c6e 100644 --- a/src/PythonMetaTrader5/application/execution.py +++ b/src/PythonMetaTrader5/application/execution.py @@ -10,8 +10,8 @@ from PythonMetaTrader5.domain.errors import ErrorKind, TradeError from PythonMetaTrader5.domain.market import TradeReceipt from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest -from PythonMetaTrader5.domain.retcodes import Outcome, classify, error_for -from PythonMetaTrader5.result import Err, Result +from PythonMetaTrader5.domain.retcodes import DONE, DONE_PARTIAL, Outcome, classify, error_for +from PythonMetaTrader5.result import Err, Ok, Result log = logging.getLogger("PythonMetaTrader5") @@ -54,7 +54,7 @@ def execute( last = sent.value outcome = classify(last.retcode) if outcome is Outcome.SUCCESS: - return sent + return _confirm(request.value, last) if outcome is Outcome.FAIL: return Err(replace(error_for(last.retcode), receipt=last)) log.warning("retcode %s on attempt %s/%s", last.retcode, attempt, policy.attempts) @@ -70,3 +70,35 @@ def execute( receipt=last, ) ) + + +def _confirm( + request: OrderRequest | CancelRequest, receipt: TradeReceipt +) -> Result[TradeReceipt, TradeError]: + """Only DONE proves a market deal (entry or close) executed in full. + + PARTIAL leaves volume unfilled (an entry is smaller than asked, a close leaves + a remainder open) and PLACED means queued, not executed. Both come back as + errors carrying the receipt, and neither is retried: part of the deal may + already exist, so re-sending could double it. + """ + is_deal = isinstance(request, OrderRequest) and request.pending is None + if not is_deal or receipt.retcode == DONE: + return Ok(receipt) + if receipt.retcode == DONE_PARTIAL: + return Err( + TradeError( + ErrorKind.PARTIAL_FILL, + f"executed {receipt.volume} of the requested lots", + retcode=receipt.retcode, + receipt=receipt, + ) + ) + return Err( + TradeError( + ErrorKind.OUTCOME_UNKNOWN, + "accepted but not executed yet; check positions before re-sending", + retcode=receipt.retcode, + receipt=receipt, + ) + ) diff --git a/src/PythonMetaTrader5/application/ports.py b/src/PythonMetaTrader5/application/ports.py index a498bbf..b7fab49 100644 --- a/src/PythonMetaTrader5/application/ports.py +++ b/src/PythonMetaTrader5/application/ports.py @@ -2,6 +2,7 @@ from __future__ import annotations +import operator from dataclasses import dataclass, field from typing import Protocol @@ -22,6 +23,26 @@ class Credentials: timeout_ms: int = 60_000 +def parse_login(login: object) -> int | None: + """Account number from an int-like value or an ASCII digit string, else None. + + int() is deliberately avoided: int(True) == 1 and int(12345678.9) == 12345678 + would log into another account without any error, and int() accepts + non-ASCII digits such as "\u0661\u0662\u0663". + """ + if isinstance(login, bool): + return None + if isinstance(login, str): + text = login.strip() + number = int(text) if text.isascii() and text.isdecimal() else 0 + else: + try: + number = operator.index(login) # type: ignore[arg-type] + except TypeError: + return None + return number if number > 0 else None + + class Terminal(Protocol): def connect(self, credentials: Credentials) -> Result[None, TradeError]: ... diff --git a/src/PythonMetaTrader5/application/trader.py b/src/PythonMetaTrader5/application/trader.py index f82361e..b13bf1e 100644 --- a/src/PythonMetaTrader5/application/trader.py +++ b/src/PythonMetaTrader5/application/trader.py @@ -12,7 +12,6 @@ from PythonMetaTrader5.domain.market import PendingKind, PendingOrder, Position, TradeReceipt from PythonMetaTrader5.domain.orders import Side, validate_comment from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest -from PythonMetaTrader5.domain.retcodes import DONE, DONE_PARTIAL from PythonMetaTrader5.domain.stops import Stop from PythonMetaTrader5.domain.symbol import SymbolSpec from PythonMetaTrader5.result import Err, Ok, Result @@ -259,18 +258,7 @@ def build() -> Result[OrderRequest | CancelRequest, TradeError]: ) ) - closed = execute(self._terminal, self._clock, build, self._retry) - # Only DONE proves the position is gone. PARTIAL leaves a remainder open and - # PLACED means the close order is queued, not executed: both must surface. - if isinstance(closed, Err) or closed.value.retcode == DONE: - return closed - receipt = closed.value - kind, message = ( - (ErrorKind.PARTIAL_FILL, f"closed {receipt.volume} of {position.volume} lots") - if receipt.retcode == DONE_PARTIAL - else (ErrorKind.OUTCOME_UNKNOWN, "close order accepted but not executed yet") - ) - return Err(TradeError(kind, message, retcode=receipt.retcode, receipt=receipt)) + return execute(self._terminal, self._clock, build, self._retry) def _cancel_one(self, order: PendingOrder) -> Result[TradeReceipt, TradeError]: request = CancelRequest(order=order.ticket) diff --git a/src/PythonMetaTrader5/connection.py b/src/PythonMetaTrader5/connection.py index e6f5a30..f01cc8a 100644 --- a/src/PythonMetaTrader5/connection.py +++ b/src/PythonMetaTrader5/connection.py @@ -7,7 +7,7 @@ from PythonMetaTrader5.adapters.mt5_terminal import MetaTrader5Terminal from PythonMetaTrader5.adapters.system_clock import SystemClock from PythonMetaTrader5.application.execution import RetryPolicy -from PythonMetaTrader5.application.ports import Credentials +from PythonMetaTrader5.application.ports import Credentials, parse_login from PythonMetaTrader5.application.trader import Trader from PythonMetaTrader5.domain.errors import ErrorKind, TradeError from PythonMetaTrader5.result import Err, Ok, Result @@ -27,7 +27,7 @@ def connect( retry: RetryPolicy | None = None, ) -> Result[Trader, TradeError]: """Start (or attach to) the MT5 terminal, log in, and return a ready Trader.""" - account = _account_number(login) + account = parse_login(login) if account is None: return Err( TradeError( @@ -46,15 +46,3 @@ def connect( # balance, which do not belong in application logs. log.info("connected to %s as %s", server, account) return Ok(Trader(terminal, SystemClock(), magic=magic, deviation=deviation, retry=retry)) - - -def _account_number(login: object) -> int | None: - # Exact types only: int(True) == 1 and int(12345678.9) == 12345678 would log - # into a different account than the caller meant, without any error. - if isinstance(login, str) and login.strip().isdigit(): - number = int(login) - elif type(login) is int: - number = login - else: - return None - return number if number > 0 else None diff --git a/src/PythonMetaTrader5/domain/symbol.py b/src/PythonMetaTrader5/domain/symbol.py index b5eeec1..b72b943 100644 --- a/src/PythonMetaTrader5/domain/symbol.py +++ b/src/PythonMetaTrader5/domain/symbol.py @@ -38,7 +38,9 @@ class SymbolSpec: volume_max: float volume_step: float filling_flags: int - exchange_execution: bool = False + # Required on purpose: a default would quietly treat an exchange symbol as + # market execution and send limits that cancel instead of resting. + exchange_execution: bool def normalize_price(self, price: float) -> float: # A price must sit on the tick grid, not merely have `digits` decimals: diff --git a/src/PythonMetaTrader5/legacy/broker.py b/src/PythonMetaTrader5/legacy/broker.py index 9793937..114296a 100644 --- a/src/PythonMetaTrader5/legacy/broker.py +++ b/src/PythonMetaTrader5/legacy/broker.py @@ -13,7 +13,7 @@ from PythonMetaTrader5.adapters.mt5_terminal import MetaTrader5Terminal from PythonMetaTrader5.adapters.system_clock import SystemClock -from PythonMetaTrader5.application.ports import Clock, Credentials, Terminal +from PythonMetaTrader5.application.ports import Clock, Credentials, Terminal, parse_login from PythonMetaTrader5.application.trader import Trader from PythonMetaTrader5.domain.errors import TradeError from PythonMetaTrader5.domain.market import PendingKind, TradeReceipt @@ -50,7 +50,12 @@ def __init__( ) self.log = log self.server = str(server) - self._credentials = Credentials(int(log), str(password), self.server) + account = parse_login(log) + if account is None: + # Programming error, raised as 2.x did for non-numeric logins; silently + # coercing True or 12345678.9 would trade on another account. + raise ValueError(f"login must be a positive integer, got {log!r}") + self._credentials = Credentials(account, str(password), self.server) self._clock = clock or SystemClock() self._terminal = terminal or _load_terminal() self._trader = Trader(self._terminal, self._clock) if self._terminal else None diff --git a/tests/unit/fake_mt5.py b/tests/unit/fake_mt5.py index 7044f06..cb0e4e2 100644 --- a/tests/unit/fake_mt5.py +++ b/tests/unit/fake_mt5.py @@ -24,6 +24,7 @@ "POSITION_TYPE_BUY": 0, "POSITION_TYPE_SELL": 1, "SYMBOL_TRADE_EXECUTION_EXCHANGE": 3, + "RES_S_OK": 1, "RES_E_INVALID_PARAMS": -2, "RES_E_NO_MEMORY": -3, "RES_E_NOT_FOUND": -4, diff --git a/tests/unit/fakes.py b/tests/unit/fakes.py index 0733772..084ac5a 100644 --- a/tests/unit/fakes.py +++ b/tests/unit/fakes.py @@ -21,6 +21,7 @@ volume_max=100.0, volume_step=0.01, filling_flags=1, + exchange_execution=False, ) XAUUSD = SymbolSpec( name="XAUUSD", @@ -31,6 +32,7 @@ volume_max=50.0, volume_step=0.01, filling_flags=2, + exchange_execution=False, ) diff --git a/tests/unit/test_confirmation.py b/tests/unit/test_confirmation.py new file mode 100644 index 0000000..30d51b5 --- /dev/null +++ b/tests/unit/test_confirmation.py @@ -0,0 +1,85 @@ +"""Only an answer that proves the requested effect counts as success.""" + +import operator + +import pytest + +from PythonMetaTrader5 import Broker, connect +from PythonMetaTrader5.adapters.mt5_terminal import MetaTrader5Terminal +from PythonMetaTrader5.application.ports import Credentials +from PythonMetaTrader5.application.trader import Trader +from PythonMetaTrader5.domain.errors import ErrorKind +from PythonMetaTrader5.result import Err, Ok + +from .fake_mt5 import FakeMT5, symbol_info +from .fakes import FakeClock, FakeTerminal + + +@pytest.mark.parametrize( + ("retcode", "kind"), [(10010, ErrorKind.PARTIAL_FILL), (10008, ErrorKind.OUTCOME_UNKNOWN)] +) +def test_market_entry_succeeds_only_when_done( + trader: Trader, terminal: FakeTerminal, retcode: int, kind: ErrorKind +) -> None: + terminal.retcodes.append(retcode) + result = trader.open_position("EURUSD", "buy", 0.1) + assert isinstance(result, Err) + assert result.error.kind is kind + assert result.error.receipt is not None + assert len(terminal.sent) == 1 # never re-sent: something may already be open + + +@pytest.mark.parametrize("retcode", [10008, 10009]) +def test_pending_entry_succeeds_when_placed( + trader: Trader, terminal: FakeTerminal, retcode: int +) -> None: + terminal.retcodes.append(retcode) + assert isinstance(trader.place_limit_order("EURUSD", "buy", 0.1, 1.0), Ok) + + +@pytest.mark.parametrize("login", ["²", "١٢٣", " 12a", ""]) +def test_non_ascii_or_malformed_login_is_an_error(login: str) -> None: + result = connect(login, "pw", "Demo") + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_ARGUMENT + + +class IndexLike: + def __index__(self) -> int: + return 12345678 + + +def test_integer_like_login_is_accepted(no_real_terminal: FakeMT5) -> None: + assert operator.index(IndexLike()) == 12345678 + assert isinstance(connect(IndexLike(), "pw", "Demo"), Ok) # type: ignore[arg-type] + assert no_real_terminal.calls[0][2]["login"] == 12345678 + + +@pytest.mark.parametrize("login", [True, 12345678.9, "abc"]) +def test_legacy_broker_rejects_logins_it_would_coerce(login: object) -> None: + with ( + pytest.warns(DeprecationWarning, match="connect"), + pytest.raises(ValueError, match="login"), + ): + Broker(login, "pw", "Demo", terminal=FakeTerminal(), clock=FakeClock()) # type: ignore[arg-type] + + +def test_failed_relogin_keeps_a_working_session() -> None: + mt5 = FakeMT5() + adapter = MetaTrader5Terminal(mt5) + assert adapter.connect(Credentials(1, "pw", "s")) == Ok(None) + mt5.initialize_ok = False + assert isinstance(adapter.connect(Credentials(1, "bad", "s")), Err) + assert "shutdown" not in [name for name, _, _ in mt5.calls] + + +def test_exchange_execution_is_read_from_the_symbol() -> None: + mt5 = FakeMT5() + mt5.symbols["SBER"] = symbol_info("SBER") + mt5.symbols["SBER"].trade_exemode = 3 + mt5.symbols["EURUSD"] = symbol_info() + adapter = MetaTrader5Terminal(mt5) + sber, eurusd = adapter.symbol("SBER"), adapter.symbol("EURUSD") + assert isinstance(sber, Ok) + assert isinstance(eurusd, Ok) + assert (sber.value.exchange_execution, eurusd.value.exchange_execution) == (True, False) diff --git a/tests/unit/test_mt5_adapter.py b/tests/unit/test_mt5_adapter.py index 8109a18..2aded83 100644 --- a/tests/unit/test_mt5_adapter.py +++ b/tests/unit/test_mt5_adapter.py @@ -47,7 +47,8 @@ def test_connect_passes_credentials_and_reports_failure( assert result.error.kind is ErrorKind.CONNECTION_FAILED assert "Authorization failed" in result.error.message assert "p" not in result.error.message.split() - assert mt5.calls[-2][1] == ("C:/mt5/terminal64.exe",) + # The first login opened the session, so a failed re-login must not close it. + assert mt5.calls[-1][1] == ("C:/mt5/terminal64.exe",) def test_password_never_appears_in_repr() -> None: diff --git a/tests/unit/test_safety_edges.py b/tests/unit/test_safety_edges.py index 84975d6..1a1cbe8 100644 --- a/tests/unit/test_safety_edges.py +++ b/tests/unit/test_safety_edges.py @@ -111,16 +111,12 @@ def test_first_missing_quote_after_selection_is_waited_for( assert len(terminal.sent) == 1 -def test_partial_close_is_a_failure_but_partial_open_is_not( - trader: Trader, terminal: FakeTerminal -) -> None: +def test_partial_close_is_a_failure(trader: Trader, terminal: FakeTerminal) -> None: terminal.open_positions = [position(1)] terminal.retcodes.append(10010) closed = trader.close_positions("EURUSD") assert isinstance(closed, Err) assert closed.error.errors[0].kind is ErrorKind.PARTIAL_FILL - terminal.retcodes.append(10010) - assert isinstance(trader.open_position("EURUSD", "buy", 0.1), Ok) def test_limit_order_uses_a_filling_mode_the_symbol_allows( diff --git a/tests/unit/test_stops.py b/tests/unit/test_stops.py index 22d118d..6f51b83 100644 --- a/tests/unit/test_stops.py +++ b/tests/unit/test_stops.py @@ -13,6 +13,7 @@ volume_max=100.0, volume_step=0.01, filling_flags=1, + exchange_execution=False, ) diff --git a/tests/unit/test_symbol.py b/tests/unit/test_symbol.py index 78e19f2..2ed9c01 100644 --- a/tests/unit/test_symbol.py +++ b/tests/unit/test_symbol.py @@ -15,6 +15,7 @@ def eurusd(**overrides: object) -> SymbolSpec: "volume_max": 100.0, "volume_step": 0.01, "filling_flags": 1, + "exchange_execution": False, } fields.update(overrides) return SymbolSpec(**fields) # type: ignore[arg-type] From bc237d4838df16162060ef8eefd8fec16d44efcf Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 02:29:47 +0100 Subject: [PATCH 11/28] fix: always release the MT5 session after a failed login Fourth review round. The previous commit kept a "live" session after a failed re-login using a per-adapter flag. That was wrong: MT5 has one session per process and connect() builds a new adapter each time, so the flag protected nothing, and it stopped login(ToEffect=True) from ever recovering because the half-open session was never released. Reproduced by failing tests first. - The adapter always calls shutdown() after a failed initialize(); Broker marks itself disconnected so nothing trades on a released session. - Credentials validates the login itself, so no construction path can hand MT5 True or a float. - PARTIAL_FILL names the requested size and warns that with RETURN filling the remainder may still be working. - A detached comment about RES_S_OK moved next to the code it explains. --- .../adapters/mt5_terminal.py | 18 +++++++--------- .../application/execution.py | 10 ++++++--- src/PythonMetaTrader5/application/ports.py | 6 ++++++ src/PythonMetaTrader5/legacy/broker.py | 2 ++ tests/unit/test_confirmation.py | 21 ++++++++++++++++--- tests/unit/test_mt5_adapter.py | 4 ++-- 6 files changed, 43 insertions(+), 18 deletions(-) diff --git a/src/PythonMetaTrader5/adapters/mt5_terminal.py b/src/PythonMetaTrader5/adapters/mt5_terminal.py index ed6bb8d..0460024 100644 --- a/src/PythonMetaTrader5/adapters/mt5_terminal.py +++ b/src/PythonMetaTrader5/adapters/mt5_terminal.py @@ -23,8 +23,6 @@ from PythonMetaTrader5.domain.symbol import Filling, SymbolSpec from PythonMetaTrader5.result import Err, Ok, Result -# MT5 reports "nothing found" and "call failed" both as None; only last_error() -# tells them apart. 1 is RES_S_OK. # last_error() codes for which order_send provably never left this process # (bad arguments, no IPC link, terminal refused). Any other failure (send, # receive, timeout) may have reached the server, so its outcome is unknown. @@ -65,10 +63,9 @@ def __init__(self, mt5: Any) -> None: self._exchange_execution = mt5.SYMBOL_TRADE_EXECUTION_EXCHANGE self._not_sent = frozenset(getattr(mt5, name) for name in _NOT_SENT_CODES) self._auto_trading_disabled = mt5.RES_E_AUTO_TRADING_DISABLED + # MT5 reports "nothing found" and "call failed" both as None; only a + # last_error() of RES_S_OK tells "nothing found" apart. self._ok = mt5.RES_S_OK - # MT5 keeps one session per process; it is only ours to close after a - # failed login if no earlier login of this adapter opened it. - self._session_open = False @classmethod def load(cls) -> Result[MetaTrader5Terminal, TradeError]: @@ -92,13 +89,14 @@ def connect(self, credentials: Credentials) -> Result[None, TradeError]: server=credentials.server, timeout=credentials.timeout_ms, ): - self._session_open = True return Ok(None) error = self._last_error() - if not self._session_open: - # initialize() may have attached to (or launched) the terminal before - # the login failed; that half-session makes every later attempt fail. - self._mt5.shutdown() + # Always released: MT5 has one session per process, so after a failed login + # it is unusable for everyone, and a half-open one makes every later + # initialize() fail (login(ToEffect=True) could never recover). A per-adapter + # "keep the live session" flag was tried and dropped: connect() builds a + # new adapter each time, so the flag protected nothing. + self._mt5.shutdown() return Err( TradeError( ErrorKind.CONNECTION_FAILED, diff --git a/src/PythonMetaTrader5/application/execution.py b/src/PythonMetaTrader5/application/execution.py index 6914c6e..77f1462 100644 --- a/src/PythonMetaTrader5/application/execution.py +++ b/src/PythonMetaTrader5/application/execution.py @@ -82,14 +82,18 @@ def _confirm( errors carrying the receipt, and neither is retried: part of the deal may already exist, so re-sending could double it. """ - is_deal = isinstance(request, OrderRequest) and request.pending is None - if not is_deal or receipt.retcode == DONE: + if ( + not isinstance(request, OrderRequest) + or request.pending is not None + or receipt.retcode == DONE + ): return Ok(receipt) if receipt.retcode == DONE_PARTIAL: return Err( TradeError( ErrorKind.PARTIAL_FILL, - f"executed {receipt.volume} of the requested lots", + f"executed {receipt.volume} of {request.volume} lots; with RETURN " + "filling the rest may still be working as an order", retcode=receipt.retcode, receipt=receipt, ) diff --git a/src/PythonMetaTrader5/application/ports.py b/src/PythonMetaTrader5/application/ports.py index b7fab49..e70c9d9 100644 --- a/src/PythonMetaTrader5/application/ports.py +++ b/src/PythonMetaTrader5/application/ports.py @@ -22,6 +22,12 @@ class Credentials: path: str | None = None timeout_ms: int = 60_000 + def __post_init__(self) -> None: + # The type itself enforces the login rule, so no construction path can + # hand MT5 True or a float that it would turn into another account. + if parse_login(self.login) != self.login: + raise ValueError(f"login must be a positive integer, got {self.login!r}") + def parse_login(login: object) -> int | None: """Account number from an int-like value or an ASCII digit string, else None. diff --git a/src/PythonMetaTrader5/legacy/broker.py b/src/PythonMetaTrader5/legacy/broker.py index 114296a..d67e68c 100644 --- a/src/PythonMetaTrader5/legacy/broker.py +++ b/src/PythonMetaTrader5/legacy/broker.py @@ -71,6 +71,8 @@ def login(self, ToEffect: bool = False) -> bool: log.info("%s: logged in to %s", self.log, self.server) self._connected = True return True + # The adapter released the session, so nothing may trade until a login works. + self._connected = False log.error("%s: %s", self.log, result.error) if not ToEffect: return False diff --git a/tests/unit/test_confirmation.py b/tests/unit/test_confirmation.py index 30d51b5..f413c32 100644 --- a/tests/unit/test_confirmation.py +++ b/tests/unit/test_confirmation.py @@ -8,7 +8,7 @@ from PythonMetaTrader5.adapters.mt5_terminal import MetaTrader5Terminal from PythonMetaTrader5.application.ports import Credentials from PythonMetaTrader5.application.trader import Trader -from PythonMetaTrader5.domain.errors import ErrorKind +from PythonMetaTrader5.domain.errors import ErrorKind, TradeError from PythonMetaTrader5.result import Err, Ok from .fake_mt5 import FakeMT5, symbol_info @@ -64,13 +64,28 @@ def test_legacy_broker_rejects_logins_it_would_coerce(login: object) -> None: Broker(login, "pw", "Demo", terminal=FakeTerminal(), clock=FakeClock()) # type: ignore[arg-type] -def test_failed_relogin_keeps_a_working_session() -> None: +def test_failed_relogin_releases_the_session_so_a_retry_can_recover() -> None: mt5 = FakeMT5() adapter = MetaTrader5Terminal(mt5) assert adapter.connect(Credentials(1, "pw", "s")) == Ok(None) mt5.initialize_ok = False assert isinstance(adapter.connect(Credentials(1, "bad", "s")), Err) - assert "shutdown" not in [name for name, _, _ in mt5.calls] + assert [name for name, _, _ in mt5.calls] == ["initialize", "initialize", "shutdown"] + + +def test_broker_stops_trading_after_a_failed_relogin(terminal: FakeTerminal) -> None: + with pytest.warns(DeprecationWarning, match="connect"): + broker = Broker(1, "pw", "Demo", terminal=terminal, clock=FakeClock()) + terminal.connect_failure = TradeError(ErrorKind.CONNECTION_FAILED, "down") + assert broker.login() is False + assert broker.Buy("EURUSD", 0.1) is None + assert terminal.sent == [] + + +@pytest.mark.parametrize("login", [True, 1.5, 0]) +def test_credentials_refuse_logins_mt5_would_coerce(login: object) -> None: + with pytest.raises(ValueError, match="login"): + Credentials(login, "pw", "s") # type: ignore[arg-type] def test_exchange_execution_is_read_from_the_symbol() -> None: diff --git a/tests/unit/test_mt5_adapter.py b/tests/unit/test_mt5_adapter.py index 2aded83..2700e28 100644 --- a/tests/unit/test_mt5_adapter.py +++ b/tests/unit/test_mt5_adapter.py @@ -47,8 +47,8 @@ def test_connect_passes_credentials_and_reports_failure( assert result.error.kind is ErrorKind.CONNECTION_FAILED assert "Authorization failed" in result.error.message assert "p" not in result.error.message.split() - # The first login opened the session, so a failed re-login must not close it. - assert mt5.calls[-1][1] == ("C:/mt5/terminal64.exe",) + assert mt5.calls[-2][1] == ("C:/mt5/terminal64.exe",) + assert mt5.calls[-1][0] == "shutdown" def test_password_never_appears_in_repr() -> None: From 16cc80bc423e51b30400fdcb9e6ae30ee6c0c58b Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 02:31:55 +0100 Subject: [PATCH 12/28] ci: pin publish workflow actions to commit SHAs Semgrep MEDIUM (github-actions-mutable-action-tag) x2 in python-publish.yml. Pinned to the SHAs the v4/v5 tags point at today, so publishing behaves exactly as before while a re-pointed tag can no longer inject code into the job that holds the PyPI token. --- .github/workflows/python-publish.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/python-publish.yml b/.github/workflows/python-publish.yml index 59494e3..e0ac010 100644 --- a/.github/workflows/python-publish.yml +++ b/.github/workflows/python-publish.yml @@ -17,10 +17,10 @@ jobs: steps: - name: Checkout - uses: actions/checkout@v4 + uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 - name: Setup Python - uses: actions/setup-python@v5 + uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5 with: python-version: '3.x' From 55be3e22319704bccc6dde893542bb530a475a44 Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 02:51:54 +0100 Subject: [PATCH 13/28] fix: refuse zero stops, bad tickets and non-finite numbers; serialize MT5 calls Found by three independent reviews after the fourth /code-review round. - sl=0 / tp=0 (or a price that snaps to 0.0, or a points distance that goes below zero) is INVALID_STOPS. MT5 reads 0.0 as "no stop", so a webhook with a missing SL field opened an unprotected position and reported Ok. - A ticket that is not a positive integer (0, -5, True, 1.0, "7") is INVALID_ARGUMENT before positions_get is called; positions_get(ticket=0) may mean "no filter", which would close the whole account. - Volume and prices must be positive finite numbers (numbers.Real, not bool): NaN/inf raised ValueError/OverflowError instead of returning Err, and volume=True traded one lot. volume_step <= 0 is an Err, not a ZeroDivisionError. - The adapter applies symbol and ticket together; MT5 drops `symbol` once `ticket` is given, so positions("EURUSD", ticket=t) could return a position on another symbol. - Every adapter call holds a module-level RLock, so an MT5 call and the last_error() read that explains it cannot interleave with another thread. A per-adapter lock instead of a module lock: rejected, because connect() builds a new adapter per call and two Traders share the one process-global session, so per-adapter locks protect nothing. Splits (300-line limit, each one concern): - domain/inputs.py: input rules with no I/O; plain functions, not a port. - application/entries.py: Entry and validate_entry, the one place raw entry input becomes a request; Entry.request is an entity method instead of a Trader helper because it needs only the entry's own data. - adapters/mt5_mapping.py: pure MT5-object -> domain mapping. Removed/renamed private helpers; grep over src tests docs scripts *.md .github for _reject_empty|_as_stop|_order_type_table|_validate_entry| _entry_request|\._position\(|_Entry\b: no matches outside stale __pycache__. RED: 36 of 40 new cases failed (4 of the volume cases already passed: 0, -0.1 and -inf are caught by the range check, and None by float() raising), the resolve-to-zero cases failed with the guard disabled, and the lock test failed before the lock existed. --- src/PythonMetaTrader5/adapters/mt5_mapping.py | 84 +++++++++++ .../adapters/mt5_terminal.py | 111 +++++--------- src/PythonMetaTrader5/application/entries.py | 104 +++++++++++++ src/PythonMetaTrader5/application/trader.py | 113 ++++---------- src/PythonMetaTrader5/domain/inputs.py | 59 ++++++++ src/PythonMetaTrader5/domain/symbol.py | 4 + tests/unit/fakes.py | 20 +++ tests/unit/test_input_guards.py | 140 ++++++++++++++++++ 8 files changed, 477 insertions(+), 158 deletions(-) create mode 100644 src/PythonMetaTrader5/adapters/mt5_mapping.py create mode 100644 src/PythonMetaTrader5/application/entries.py create mode 100644 src/PythonMetaTrader5/domain/inputs.py create mode 100644 tests/unit/test_input_guards.py diff --git a/src/PythonMetaTrader5/adapters/mt5_mapping.py b/src/PythonMetaTrader5/adapters/mt5_mapping.py new file mode 100644 index 0000000..576b291 --- /dev/null +++ b/src/PythonMetaTrader5/adapters/mt5_mapping.py @@ -0,0 +1,84 @@ +"""Translation between MetaTrader5's raw result objects and domain models. + +Split out of mt5_terminal.py (300-line limit). Pure functions: they read fields +of MT5 objects but never call the terminal, so they need no session lock. +""" + +from __future__ import annotations + +from typing import Any + +from PythonMetaTrader5.domain.market import PendingKind, PendingOrder, Position, TradeReceipt +from PythonMetaTrader5.domain.orders import Side + +OrderTypes = dict[tuple[Side, PendingKind | None], int] + + +def order_type_table(mt5: Any) -> OrderTypes: + return { + (Side.BUY, None): mt5.ORDER_TYPE_BUY, + (Side.SELL, None): mt5.ORDER_TYPE_SELL, + (Side.BUY, PendingKind.LIMIT): mt5.ORDER_TYPE_BUY_LIMIT, + (Side.SELL, PendingKind.LIMIT): mt5.ORDER_TYPE_SELL_LIMIT, + (Side.BUY, PendingKind.STOP): mt5.ORDER_TYPE_BUY_STOP, + (Side.SELL, PendingKind.STOP): mt5.ORDER_TYPE_SELL_STOP, + (Side.BUY, PendingKind.STOP_LIMIT): mt5.ORDER_TYPE_BUY_STOP_LIMIT, + (Side.SELL, PendingKind.STOP_LIMIT): mt5.ORDER_TYPE_SELL_STOP_LIMIT, + } + + +def receipt(result: Any) -> TradeReceipt: + return TradeReceipt( + retcode=int(result.retcode), + deal=int(result.deal), + order=int(result.order), + volume=float(result.volume), + price=float(result.price), + bid=float(result.bid), + ask=float(result.ask), + comment=str(result.comment), + request_id=int(result.request_id), + ) + + +def position(p: Any, position_buy: int) -> Position: + return Position( + ticket=int(p.ticket), + symbol=str(p.symbol), + side=Side.BUY if p.type == position_buy else Side.SELL, + volume=float(p.volume), + price_open=float(p.price_open), + # MT5 encodes "no stop" as 0.0, which is also a (useless) price. + sl=float(p.sl) or None, + tp=float(p.tp) or None, + price_current=float(p.price_current), + profit=float(p.profit), + time=int(p.time), + magic=int(p.magic), + comment=str(p.comment), + ) + + +def pending_orders( + raw: tuple[Any, ...], by_type: dict[int, tuple[Side, PendingKind]] +) -> list[PendingOrder]: + orders = [] + for o in raw: + key = by_type.get(int(o.type)) + # Market orders still being processed and close-by orders are not resting orders. + if key is None: + continue + side, kind = key + orders.append( + PendingOrder( + ticket=int(o.ticket), + symbol=str(o.symbol), + side=side, + kind=kind, + volume=float(o.volume_current), + price=float(o.price_open), + magic=int(o.magic), + comment=str(o.comment), + ) + ) + return orders diff --git a/src/PythonMetaTrader5/adapters/mt5_terminal.py b/src/PythonMetaTrader5/adapters/mt5_terminal.py index 0460024..dc8a310 100644 --- a/src/PythonMetaTrader5/adapters/mt5_terminal.py +++ b/src/PythonMetaTrader5/adapters/mt5_terminal.py @@ -6,19 +6,16 @@ from __future__ import annotations +import functools import importlib -from typing import Any +import threading +from collections.abc import Callable +from typing import Any, ParamSpec, TypeVar +from PythonMetaTrader5.adapters import mt5_mapping from PythonMetaTrader5.application.ports import Credentials from PythonMetaTrader5.domain.errors import ErrorKind, TradeError -from PythonMetaTrader5.domain.market import ( - PendingKind, - PendingOrder, - Position, - Tick, - TradeReceipt, -) -from PythonMetaTrader5.domain.orders import Side +from PythonMetaTrader5.domain.market import PendingOrder, Position, Tick, TradeReceipt from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest from PythonMetaTrader5.domain.symbol import Filling, SymbolSpec from PythonMetaTrader5.result import Err, Ok, Result @@ -37,12 +34,30 @@ "RES_E_INTERNAL_FAIL_CONNECT", ) +# last_error() is process-global, so a call and the error read that explains it +# must not interleave with another thread's call. The lock is module-level, not +# per adapter: connect() builds a new adapter each time, and two Traders in one +# process share the one MT5 session. Direct MetaTrader5 calls made by user code +# are outside this lock. +_SESSION = threading.RLock() +_P = ParamSpec("_P") +_R = TypeVar("_R") + + +def _serialized(method: Callable[_P, _R]) -> Callable[_P, _R]: + @functools.wraps(method) + def locked(*args: _P.args, **kwargs: _P.kwargs) -> _R: + with _SESSION: + return method(*args, **kwargs) + + return locked + class MetaTrader5Terminal: def __init__(self, mt5: Any) -> None: # `Any`: the MetaTrader5 package ships no type information. self._mt5 = mt5 - self._order_types = _order_type_table(mt5) + self._order_types = mt5_mapping.order_type_table(mt5) self._pending_by_type = { code: (side, kind) for (side, kind), code in self._order_types.items() @@ -80,6 +95,7 @@ def load(cls) -> Result[MetaTrader5Terminal, TradeError]: ) return Ok(cls(module)) + @_serialized def connect(self, credentials: Credentials) -> Result[None, TradeError]: args = (credentials.path,) if credentials.path else () if self._mt5.initialize( @@ -104,9 +120,11 @@ def connect(self, credentials: Credentials) -> Result[None, TradeError]: ) ) + @_serialized def shutdown(self) -> None: self._mt5.shutdown() + @_serialized def symbol(self, name: str) -> Result[SymbolSpec, TradeError]: info = self._mt5.symbol_info(name) if info is None: @@ -133,6 +151,7 @@ def symbol(self, name: str) -> Result[SymbolSpec, TradeError]: ) ) + @_serialized def tick(self, name: str) -> Result[Tick, TradeError]: tick = self._mt5.symbol_info_tick(name) # A zero side means no quote yet; trading at price 0 must never be attempted. @@ -140,25 +159,15 @@ def tick(self, name: str) -> Result[Tick, TradeError]: return Err(TradeError(ErrorKind.NO_PRICE, f"no quote for {name!r}")) return Ok(Tick(bid=float(tick.bid), ask=float(tick.ask))) + @_serialized def send(self, request: OrderRequest | CancelRequest) -> Result[TradeReceipt, TradeError]: payload = self._payload(request) result = self._mt5.order_send(payload) if result is None: return Err(self._send_failure()) - return Ok( - TradeReceipt( - retcode=int(result.retcode), - deal=int(result.deal), - order=int(result.order), - volume=float(result.volume), - price=float(result.price), - bid=float(result.bid), - ask=float(result.ask), - comment=str(result.comment), - request_id=int(result.request_id), - ) - ) + return Ok(mt5_mapping.receipt(result)) + @_serialized def positions( self, *, symbol: str | None = None, ticket: int | None = None ) -> Result[list[Position], TradeError]: @@ -170,8 +179,11 @@ def positions( raw = self._listing(self._mt5.positions_get(**query), "positions_get") if isinstance(raw, Err): return raw - return Ok([self._position(p) for p in raw.value]) + found = [mt5_mapping.position(p, self._position_buy) for p in raw.value] + # MT5 ignores `symbol` once `ticket` is given; the port promises both apply. + return Ok([p for p in found if symbol is None or p.symbol == symbol]) + @_serialized def pending_orders( self, *, symbol: str | None = None ) -> Result[list[PendingOrder], TradeError]: @@ -179,26 +191,7 @@ def pending_orders( raw = self._listing(self._mt5.orders_get(**query), "orders_get") if isinstance(raw, Err): return raw - orders = [] - for o in raw.value: - key = self._pending_by_type.get(int(o.type)) - # Market orders still being processed and close-by orders are not resting orders. - if key is None: - continue - side, kind = key - orders.append( - PendingOrder( - ticket=int(o.ticket), - symbol=str(o.symbol), - side=side, - kind=kind, - volume=float(o.volume_current), - price=float(o.price_open), - magic=int(o.magic), - comment=str(o.comment), - ) - ) - return Ok(orders) + return Ok(mt5_mapping.pending_orders(raw.value, self._pending_by_type)) # ------------------------------------------------------------------ helpers @@ -221,23 +214,6 @@ def _payload(self, request: OrderRequest | CancelRequest) -> dict[str, Any]: payload.update({key: value for key, value in optional.items() if value is not None}) return payload - def _position(self, p: Any) -> Position: - return Position( - ticket=int(p.ticket), - symbol=str(p.symbol), - side=Side.BUY if p.type == self._position_buy else Side.SELL, - volume=float(p.volume), - price_open=float(p.price_open), - # MT5 encodes "no stop" as 0.0, which is also a (useless) price. - sl=float(p.sl) or None, - tp=float(p.tp) or None, - price_current=float(p.price_current), - profit=float(p.profit), - time=int(p.time), - magic=int(p.magic), - comment=str(p.comment), - ) - def _listing(self, raw: Any, call: str) -> Result[tuple[Any, ...], TradeError]: if raw is not None: return Ok(tuple(raw)) @@ -262,16 +238,3 @@ def _last_error(self) -> str: def _error(self) -> tuple[int, str]: code, message = self._mt5.last_error() return code, f"[{code}] {message}" - - -def _order_type_table(mt5: Any) -> dict[tuple[Side, PendingKind | None], int]: - return { - (Side.BUY, None): mt5.ORDER_TYPE_BUY, - (Side.SELL, None): mt5.ORDER_TYPE_SELL, - (Side.BUY, PendingKind.LIMIT): mt5.ORDER_TYPE_BUY_LIMIT, - (Side.SELL, PendingKind.LIMIT): mt5.ORDER_TYPE_SELL_LIMIT, - (Side.BUY, PendingKind.STOP): mt5.ORDER_TYPE_BUY_STOP, - (Side.SELL, PendingKind.STOP): mt5.ORDER_TYPE_SELL_STOP, - (Side.BUY, PendingKind.STOP_LIMIT): mt5.ORDER_TYPE_BUY_STOP_LIMIT, - (Side.SELL, PendingKind.STOP_LIMIT): mt5.ORDER_TYPE_SELL_STOP_LIMIT, - } diff --git a/src/PythonMetaTrader5/application/entries.py b/src/PythonMetaTrader5/application/entries.py new file mode 100644 index 0000000..6435c4e --- /dev/null +++ b/src/PythonMetaTrader5/application/entries.py @@ -0,0 +1,104 @@ +"""Validated entry parameters shared by market and pending entries. + +Split out of trader.py (300-line limit): this is the only place that turns raw +caller input into an entry request, so every check runs before any send. +""" + +from __future__ import annotations + +from dataclasses import dataclass + +from PythonMetaTrader5.application.ports import Terminal +from PythonMetaTrader5.domain.errors import ErrorKind, TradeError +from PythonMetaTrader5.domain.inputs import positive_number, stop_input +from PythonMetaTrader5.domain.market import PendingKind +from PythonMetaTrader5.domain.orders import Side, validate_comment +from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest +from PythonMetaTrader5.domain.stops import Stop +from PythonMetaTrader5.domain.symbol import SymbolSpec +from PythonMetaTrader5.result import Err, Ok, Result + +StopInput = Stop | float | None + + +@dataclass(frozen=True, slots=True) +class Entry: + spec: SymbolSpec + side: Side + volume: float + comment: str + stop_loss: Stop | None + take_profit: Stop | None + + def request( + self, reference: float, *, pending: PendingKind | None, deviation: int, magic: int + ) -> Result[OrderRequest | CancelRequest, TradeError]: + spec, side = self.spec, self.side + sl = self.stop_loss.stop_loss(side, reference, spec) if self.stop_loss else None + tp = self.take_profit.take_profit(side, reference, spec) if self.take_profit else None + for name, level in (("sl", sl), ("tp", tp)): + # A tiny price snaps to 0.0 and a long points distance goes below + # zero; MT5 would read the first as "no stop". + if level is not None and level <= 0: + message = f"{name} resolves to {level} on {spec.name}" + return Err(TradeError(ErrorKind.INVALID_STOPS, message)) + return Ok( + OrderRequest( + symbol=spec.name, + side=side, + volume=self.volume, + price=reference, + filling=spec.market_filling() if pending is None else spec.pending_filling(), + deviation=deviation, + magic=magic, + comment=self.comment, + sl=sl, + tp=tp, + pending=pending, + ) + ) + + +def validate_entry( + terminal: Terminal, + symbol: str, + side: Side | str, + volume: float, + *, + comment: str | None, + sl: StopInput, + tp: StopInput, +) -> Result[Entry, TradeError]: + # Every check that needs no terminal runs first, so bad input never costs a + # symbol lookup (which may add the symbol to Market Watch). + values = _caller_values(side, comment, sl, tp) + if isinstance(values, Err): + return values + amount = positive_number(volume, ErrorKind.INVALID_VOLUME, "volume") + if isinstance(amount, Err): + return amount + spec = terminal.symbol(symbol) + if isinstance(spec, Err): + return spec + lots = spec.value.validate_volume(amount.value) + if isinstance(lots, Err): + return lots + parsed_side, text, stop_loss, take_profit = values.value + return Ok(Entry(spec.value, parsed_side, lots.value, text, stop_loss, take_profit)) + + +def _caller_values( + side: Side | str, comment: str | None, sl: StopInput, tp: StopInput +) -> Result[tuple[Side, str, Stop | None, Stop | None], TradeError]: + parsed_side = Side.parse(side) + if isinstance(parsed_side, Err): + return parsed_side + text = validate_comment(comment) + if isinstance(text, Err): + return text + stop_loss, take_profit = stop_input(sl, "sl"), stop_input(tp, "tp") + if isinstance(stop_loss, Err): + return stop_loss + if isinstance(take_profit, Err): + return take_profit + return Ok((parsed_side.value, text.value, stop_loss.value, take_profit.value)) diff --git a/src/PythonMetaTrader5/application/trader.py b/src/PythonMetaTrader5/application/trader.py index b13bf1e..acceafa 100644 --- a/src/PythonMetaTrader5/application/trader.py +++ b/src/PythonMetaTrader5/application/trader.py @@ -2,32 +2,21 @@ from __future__ import annotations -from dataclasses import dataclass, replace +from dataclasses import replace from types import TracebackType from PythonMetaTrader5.application.batch import BatchFailure, run_batch, with_magic +from PythonMetaTrader5.application.entries import StopInput, validate_entry from PythonMetaTrader5.application.execution import RetryPolicy, execute from PythonMetaTrader5.application.ports import Clock, Terminal from PythonMetaTrader5.domain.errors import ErrorKind, TradeError +from PythonMetaTrader5.domain.inputs import positive_number, symbol_filter, ticket_filter from PythonMetaTrader5.domain.market import PendingKind, PendingOrder, Position, TradeReceipt from PythonMetaTrader5.domain.orders import Side, validate_comment from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest -from PythonMetaTrader5.domain.stops import Stop from PythonMetaTrader5.domain.symbol import SymbolSpec from PythonMetaTrader5.result import Err, Ok, Result -StopInput = Stop | float | None - - -@dataclass(frozen=True, slots=True) -class _Entry: - """Validated parameters shared by market and pending entries.""" - - spec: SymbolSpec - side: Side - volume: float - comment: str - class Trader: def __init__( @@ -64,20 +53,23 @@ def open_position( fresh quote. An explicit ``price`` is sent once: re-sending the same price after a requote cannot succeed. """ - entry = self._validate_entry(symbol, side, volume, comment) + entry = validate_entry(self._terminal, symbol, side, volume, comment=comment, sl=sl, tp=tp) if isinstance(entry, Err): return entry e = entry.value + fixed = None if price is None else positive_number(price, ErrorKind.INVALID_PRICE, "price") + if isinstance(fixed, Err): + return fixed def build() -> Result[OrderRequest | CancelRequest, TradeError]: - if price is not None: - reference = e.spec.normalize_price(price) + if fixed is not None: + reference = e.spec.normalize_price(fixed.value) else: tick = self._terminal.tick(symbol) if isinstance(tick, Err): return tick reference = tick.value.entry_price(e.side) - return Ok(self._entry_request(e, reference, sl=sl, tp=tp, pending=None)) + return e.request(reference, pending=None, deviation=self._deviation, magic=self._magic) policy = self._retry if price is None else replace(self._retry, attempts=1) return execute(self._terminal, self._clock, build, policy) @@ -98,13 +90,22 @@ def place_limit_order( A limit on the wrong side of the market is refused by the server (INVALID_PRICE) rather than converted into a market order. """ - entry = self._validate_entry(symbol, side, volume, comment) + entry = validate_entry(self._terminal, symbol, side, volume, comment=comment, sl=sl, tp=tp) if isinstance(entry, Err): return entry e = entry.value - level = e.spec.normalize_price(price) - request = self._entry_request(e, level, sl=sl, tp=tp, pending=PendingKind.LIMIT) - return execute(self._terminal, self._clock, lambda: Ok(request), self._retry) + level = positive_number(price, ErrorKind.INVALID_PRICE, "price") + if isinstance(level, Err): + return level + request = e.request( + e.spec.normalize_price(level.value), + pending=PendingKind.LIMIT, + deviation=self._deviation, + magic=self._magic, + ) + if isinstance(request, Err): + return request + return execute(self._terminal, self._clock, lambda: request, self._retry) # ------------------------------------------------------------------- exits @@ -154,9 +155,9 @@ def cancel_pending_orders( def positions( self, symbol: str | None = None, *, ticket: int | None = None, magic: int | None = None ) -> Result[list[Position], TradeError]: - invalid = _reject_empty(symbol) - if invalid is not None: - return invalid + for check in (symbol_filter(symbol), ticket_filter(ticket)): + if isinstance(check, Err): + return check listed = self._terminal.positions(symbol=symbol, ticket=ticket) return listed if isinstance(listed, Err) else Ok(with_magic(listed.value, magic)) @@ -167,9 +168,9 @@ def pending_orders( magic: int | None = None, kind: PendingKind | None = None, ) -> Result[list[PendingOrder], TradeError]: - invalid = _reject_empty(symbol) - if invalid is not None: - return invalid + checked = symbol_filter(symbol) + if isinstance(checked, Err): + return checked listed = self._terminal.pending_orders(symbol=symbol) if isinstance(listed, Err): return listed @@ -192,47 +193,6 @@ def __exit__( # ----------------------------------------------------------------- helpers - def _validate_entry( - self, symbol: str, side: Side | str, volume: float, comment: str | None - ) -> Result[_Entry, TradeError]: - parsed_side = Side.parse(side) - if isinstance(parsed_side, Err): - return parsed_side - text = validate_comment(comment) - if isinstance(text, Err): - return text - spec = self._terminal.symbol(symbol) - if isinstance(spec, Err): - return spec - lots = spec.value.validate_volume(float(volume)) - if isinstance(lots, Err): - return lots - return Ok(_Entry(spec.value, parsed_side.value, lots.value, text.value)) - - def _entry_request( - self, - e: _Entry, - reference: float, - *, - sl: StopInput, - tp: StopInput, - pending: PendingKind | None, - ) -> OrderRequest: - stop_loss, take_profit = _as_stop(sl), _as_stop(tp) - return OrderRequest( - symbol=e.spec.name, - side=e.side, - volume=e.volume, - price=reference, - filling=e.spec.market_filling() if pending is None else e.spec.pending_filling(), - deviation=self._deviation, - magic=self._magic, - comment=e.comment, - sl=stop_loss.stop_loss(e.side, reference, e.spec) if stop_loss else None, - tp=take_profit.take_profit(e.side, reference, e.spec) if take_profit else None, - pending=pending, - ) - def _close_one( self, position: Position, spec: Result[SymbolSpec, TradeError], comment: str ) -> Result[TradeReceipt, TradeError]: @@ -263,18 +223,3 @@ def build() -> Result[OrderRequest | CancelRequest, TradeError]: def _cancel_one(self, order: PendingOrder) -> Result[TradeReceipt, TradeError]: request = CancelRequest(order=order.ticket) return execute(self._terminal, self._clock, lambda: Ok(request), self._retry) - - -def _reject_empty(symbol: str | None) -> Err[TradeError] | None: - # "" is rejected rather than passed on: a missing webhook field arrives as "" - # and is easily mistaken for "no filter" (2.x and the first 3.0 draft both - # dropped falsy filters), which would act on the whole account. - if symbol == "": - return Err(TradeError(ErrorKind.INVALID_ARGUMENT, "symbol must not be empty")) - return None - - -def _as_stop(value: StopInput) -> Stop | None: - if value is None or isinstance(value, Stop): - return value - return Stop.at_price(value) diff --git a/src/PythonMetaTrader5/domain/inputs.py b/src/PythonMetaTrader5/domain/inputs.py new file mode 100644 index 0000000..20e3bec --- /dev/null +++ b/src/PythonMetaTrader5/domain/inputs.py @@ -0,0 +1,59 @@ +"""Checks on raw caller input that MT5 would otherwise misread without an error. + +Webhook payloads arrive as loosely typed JSON. Each value below has a reading +in MT5 that is valid but almost never meant: ``sl=0`` is "no stop", +``ticket=0`` may be "no filter", ``volume=True`` is one lot. They are refused +here instead of being passed on. +""" + +from __future__ import annotations + +import math +from numbers import Integral, Real + +from PythonMetaTrader5.domain.errors import ErrorKind, TradeError +from PythonMetaTrader5.domain.stops import Stop +from PythonMetaTrader5.result import Err, Ok, Result + + +def positive_number(value: object, kind: ErrorKind, what: str) -> Result[float, TradeError]: + # numbers.Real rather than float so numpy scalars from pandas-based bots pass; + # bool is excluded explicitly because it is a Real (True == 1). + if isinstance(value, bool) or not isinstance(value, Real): + return Err(TradeError(kind, f"{what} must be a number, got {value!r}")) + number = float(value) + if not math.isfinite(number) or number <= 0: + return Err(TradeError(kind, f"{what} must be a positive finite number, got {value!r}")) + return Ok(number) + + +def stop_input(value: object, what: str) -> Result[Stop | None, TradeError]: + """``None`` means no stop; a float is a price; zero is refused, never "no stop".""" + if value is None: + return Ok(None) + raw = value.value if isinstance(value, Stop) else value + checked = positive_number(raw, ErrorKind.INVALID_STOPS, what) + if isinstance(checked, Err): + return checked + return Ok(value if isinstance(value, Stop) else Stop.at_price(checked.value)) + + +def ticket_filter(ticket: object) -> Result[int | None, TradeError]: + if ticket is None: + return Ok(None) + if isinstance(ticket, bool) or not isinstance(ticket, Integral) or ticket <= 0: + return Err( + TradeError( + ErrorKind.INVALID_ARGUMENT, f"ticket must be a positive integer, got {ticket!r}" + ) + ) + return Ok(int(ticket)) + + +def symbol_filter(symbol: str | None) -> Result[str | None, TradeError]: + # "" is rejected rather than passed on: a missing webhook field arrives as "" + # and is easily mistaken for "no filter" (2.x and the first 3.0 draft both + # dropped falsy filters), which would act on the whole account. + if symbol == "": + return Err(TradeError(ErrorKind.INVALID_ARGUMENT, "symbol must not be empty")) + return Ok(symbol) diff --git a/src/PythonMetaTrader5/domain/symbol.py b/src/PythonMetaTrader5/domain/symbol.py index b72b943..10e7b9c 100644 --- a/src/PythonMetaTrader5/domain/symbol.py +++ b/src/PythonMetaTrader5/domain/symbol.py @@ -49,6 +49,10 @@ def normalize_price(self, price: float) -> float: return round(round(price / step) * step, self.digits) def validate_volume(self, volume: float) -> Result[float, TradeError]: + if self.volume_step <= 0: + # Broken symbol data: refusing is the only safe answer, guessing a + # step could send a volume the broker never allowed. + return Err(self._volume_error(volume, "not checkable against")) if volume < self.volume_min - _EPSILON or volume > self.volume_max + _EPSILON: return Err(self._volume_error(volume, "outside")) steps = (volume - self.volume_min) / self.volume_step diff --git a/tests/unit/fakes.py b/tests/unit/fakes.py index 084ac5a..efd6eae 100644 --- a/tests/unit/fakes.py +++ b/tests/unit/fakes.py @@ -4,10 +4,12 @@ from collections import deque from dataclasses import dataclass, field +from typing import Any from PythonMetaTrader5.application.ports import Credentials from PythonMetaTrader5.domain.errors import ErrorKind, TradeError from PythonMetaTrader5.domain.market import PendingOrder, Position, Tick, TradeReceipt +from PythonMetaTrader5.domain.orders import Side from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest from PythonMetaTrader5.domain.symbol import SymbolSpec from PythonMetaTrader5.result import Err, Ok, Result @@ -36,6 +38,24 @@ ) +def make_position(ticket: int = 1, **overrides: Any) -> Position: + fields: dict[str, Any] = { + "ticket": ticket, + "symbol": "EURUSD", + "side": Side.BUY, + "volume": 0.1, + "price_open": 1.1, + "sl": None, + "tp": None, + "price_current": 1.1, + "profit": 0.0, + "time": 0, + "magic": 0, + "comment": "", + } + return Position(**{**fields, **overrides}) + + def receipt(retcode: int = 10009, price: float = 0.0) -> TradeReceipt: return TradeReceipt( retcode=retcode, diff --git a/tests/unit/test_input_guards.py b/tests/unit/test_input_guards.py new file mode 100644 index 0000000..b72d5a5 --- /dev/null +++ b/tests/unit/test_input_guards.py @@ -0,0 +1,140 @@ +"""Inputs a webhook can deliver malformed must fail loudly before anything is sent.""" + +from __future__ import annotations + +import math +import threading +from dataclasses import replace + +import pytest + +from PythonMetaTrader5 import Broker, Stop +from PythonMetaTrader5.adapters.mt5_terminal import MetaTrader5Terminal +from PythonMetaTrader5.application.trader import Trader +from PythonMetaTrader5.domain.errors import ErrorKind +from PythonMetaTrader5.result import Err, Ok + +from .fake_mt5 import FakeMT5, raw_position +from .fakes import EURUSD, FakeClock, FakeTerminal, make_position + +NOT_A_STOP = [0, 0.0, -1.1, math.nan, math.inf, True, Stop.points(0), Stop.at_price(0)] +NOT_A_NUMBER = [math.nan, math.inf, -math.inf, True, "0.1", None] + + +@pytest.mark.parametrize("stop", NOT_A_STOP) +@pytest.mark.parametrize("which", ["sl", "tp"]) +def test_a_stop_of_zero_or_garbage_is_refused_not_dropped( + trader: Trader, terminal: FakeTerminal, stop: object, which: str +) -> None: + # MT5 reads sl=0 as "no stop": a missing webhook field would open unprotected. + for result in ( + trader.open_position("EURUSD", "buy", 0.1, **{which: stop}), # type: ignore[arg-type] + trader.place_limit_order("EURUSD", "buy", 0.1, 1.09, **{which: stop}), # type: ignore[arg-type] + ): + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_STOPS + assert terminal.sent == [] + + +@pytest.mark.parametrize("stop", [0.000001, Stop.points(10_000_000)]) +def test_a_stop_that_resolves_to_zero_or_below_is_refused( + trader: Trader, terminal: FakeTerminal, stop: Stop | float +) -> None: + # 0.000001 snaps to 0.0 on a 5-digit grid; 10M points below 1.1 is negative. + result = trader.open_position("EURUSD", "buy", 0.1, sl=stop) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_STOPS + assert terminal.sent == [] + + +@pytest.mark.parametrize("volume", [*NOT_A_NUMBER, 0, -0.1]) +def test_volume_that_is_not_a_positive_finite_number_is_refused( + trader: Trader, terminal: FakeTerminal, volume: object +) -> None: + result = trader.open_position("EURUSD", "buy", volume) # type: ignore[arg-type] + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_VOLUME + assert terminal.sent == [] + + +@pytest.mark.parametrize("price", [*NOT_A_NUMBER[:-1], 0, -1.0]) +def test_price_that_is_not_a_positive_finite_number_is_refused( + trader: Trader, terminal: FakeTerminal, price: object +) -> None: + for result in ( + trader.open_position("EURUSD", "buy", 0.1, price=price), # type: ignore[arg-type] + trader.place_limit_order("EURUSD", "buy", 0.1, price), # type: ignore[arg-type] + ): + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_PRICE + assert terminal.sent == [] + + +def test_a_symbol_reporting_volume_step_zero_is_an_error_not_a_crash( + trader: Trader, terminal: FakeTerminal +) -> None: + terminal.specs["EURUSD"] = replace(EURUSD, volume_step=0.0) + result = trader.open_position("EURUSD", "buy", 0.1) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_VOLUME + + +@pytest.mark.parametrize("ticket", [0, -5, True, 1.0, "7"]) +def test_a_ticket_that_is_not_a_positive_integer_never_reaches_the_terminal( + trader: Trader, terminal: FakeTerminal, ticket: object +) -> None: + # positions_get(ticket=0) may mean "no filter" and close the whole account. + terminal.open_positions = [make_position(1)] + query = trader.positions(ticket=ticket) # type: ignore[arg-type] + assert isinstance(query, Err) + assert query.error.kind is ErrorKind.INVALID_ARGUMENT + closed = trader.close_positions(ticket=ticket) # type: ignore[arg-type] + assert isinstance(closed, Err) + assert closed.error.errors[0].kind is ErrorKind.INVALID_ARGUMENT + assert terminal.sent == [] + + +def test_legacy_calls_refuse_a_zero_stop_and_a_zero_ticket(terminal: FakeTerminal) -> None: + with pytest.warns(DeprecationWarning, match="connect"): + broker = Broker(1, "pw", "Demo", terminal=terminal, clock=FakeClock()) + terminal.open_positions = [make_position(1)] + assert broker.BuySL("EURUSD", 0.1, 0) is None + assert broker.Close(None, ticket=0) is False + assert broker.GetPositions(ticket=0) == [] + assert terminal.sent == [] + + +def test_adapter_applies_symbol_and_ticket_together() -> None: + # MT5's positions_get ignores `symbol` once `ticket` is given. + mt5 = FakeMT5() + mt5.positions = (raw_position(ticket=1),) + adapter = MetaTrader5Terminal(mt5) + assert adapter.positions(symbol="XAUUSD", ticket=1) == Ok([]) + listed = adapter.positions(symbol="EURUSD", ticket=1) + assert isinstance(listed, Ok) + assert [p.ticket for p in listed.value] == [1] + + +def test_concurrent_calls_cannot_read_each_others_last_error() -> None: + # last_error() is process-global: a call and its error read must not interleave. + mt5 = FakeMT5() + entered, release = threading.Event(), threading.Event() + mt5.positions = None + + def blocking_positions_get(**_: object) -> None: + entered.set() + release.wait(5) + + mt5.positions_get = blocking_positions_get # type: ignore[method-assign] + first, second = MetaTrader5Terminal(mt5), MetaTrader5Terminal(mt5) + worker = threading.Thread(target=first.positions) + worker.start() + assert entered.wait(5) + finished = threading.Event() + other = threading.Thread(target=lambda: (second.tick("EURUSD"), finished.set())) + other.start() + blocked = not finished.wait(0.2) + release.set() + worker.join(5) + other.join(5) + assert blocked, "a second adapter ran while the first was between call and last_error()" From eeaee6b3ba07917a8566faf4f67478cf702e6660 Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 02:54:02 +0100 Subject: [PATCH 14/28] fix(legacy): return MT5-shaped positions and receipts, accept 2.x numeric strings The 2.x Broker returned raw MetaTrader5 objects. MIGRATION promised "same fields", but scripts using the missing ones broke, and no test noticed. - GetPositions(): LegacyPosition now has every TradePosition field in MT5's order (swap, identifier, reason, time_msc, time_update, time_update_msc, external_id were missing; p[1] was symbol instead of time). as_dict=True keeps exactly the 12 keys 2.x built. - Entries return LegacyReceipt, shaped like OrderSendResult: it gains retcode_external, indexing and _asdict(). `request` is always None because 3.x does not keep the echoed request. - Volume, price, sl, tp and stoplimit given as strings are converted with float(), as 2.x did; garbage raises ValueError as in 2.x. Only strings are converted: float(True) would trade a stray bool as one lot. This also fixes a regression from 55be3e2, where Buy("EURUSD", "0.1") was refused. - GetPositions(symbol, ticket=) selects by ticket alone, as in 2.x. Position gains the extra fields in the domain rather than the legacy layer keeping raw MT5 objects, which would bring MT5 types back into the facade the port exists to isolate. TradeReceipt gains retcode_external. Test helpers that built Position by hand now share fakes.make_position. Split: legacy/arguments.py takes the pure 2.x argument rules out of broker.py (300-line limit). Moved private names _legacy_stop and _no_ticket: grep over src tests docs scripts *.md .github finds no remaining use. RED: all 7 tests in test_legacy_compat.py failed before the change. --- src/PythonMetaTrader5/adapters/mt5_mapping.py | 8 ++ src/PythonMetaTrader5/domain/market.py | 11 ++ src/PythonMetaTrader5/legacy/arguments.py | 46 +++++++ src/PythonMetaTrader5/legacy/broker.py | 57 +++----- src/PythonMetaTrader5/legacy/views.py | 110 ++++++++++++--- tests/unit/fake_mt5.py | 8 ++ tests/unit/fakes.py | 8 ++ tests/unit/test_close_positions.py | 11 +- tests/unit/test_failure_paths.py | 18 +-- tests/unit/test_legacy_broker.py | 17 +-- tests/unit/test_legacy_compat.py | 128 ++++++++++++++++++ tests/unit/test_market.py | 19 +-- tests/unit/test_mt5_adapter.py | 19 +++ tests/unit/test_safety_edges.py | 17 +-- 14 files changed, 353 insertions(+), 124 deletions(-) create mode 100644 src/PythonMetaTrader5/legacy/arguments.py create mode 100644 tests/unit/test_legacy_compat.py diff --git a/src/PythonMetaTrader5/adapters/mt5_mapping.py b/src/PythonMetaTrader5/adapters/mt5_mapping.py index 576b291..cfcefde 100644 --- a/src/PythonMetaTrader5/adapters/mt5_mapping.py +++ b/src/PythonMetaTrader5/adapters/mt5_mapping.py @@ -38,6 +38,7 @@ def receipt(result: Any) -> TradeReceipt: ask=float(result.ask), comment=str(result.comment), request_id=int(result.request_id), + retcode_external=int(result.retcode_external), ) @@ -56,6 +57,13 @@ def position(p: Any, position_buy: int) -> Position: time=int(p.time), magic=int(p.magic), comment=str(p.comment), + swap=float(p.swap), + identifier=int(p.identifier), + reason=int(p.reason), + time_msc=int(p.time_msc), + time_update=int(p.time_update), + time_update_msc=int(p.time_update_msc), + external_id=str(p.external_id), ) diff --git a/src/PythonMetaTrader5/domain/market.py b/src/PythonMetaTrader5/domain/market.py index 6ba56db..a3e02fe 100644 --- a/src/PythonMetaTrader5/domain/market.py +++ b/src/PythonMetaTrader5/domain/market.py @@ -36,6 +36,16 @@ class Position: time: int magic: int comment: str + # Kept although the 3.x API does not use them: 2.x returned the raw MT5 + # object, so its users may read any of them (swap for P&L, identifier on + # netting accounts). + swap: float + identifier: int + reason: int + time_msc: int + time_update: int + time_update_msc: int + external_id: str def to_dict(self) -> dict[str, Any]: data = asdict(self) @@ -78,3 +88,4 @@ class TradeReceipt: ask: float comment: str request_id: int + retcode_external: int diff --git a/src/PythonMetaTrader5/legacy/arguments.py b/src/PythonMetaTrader5/legacy/arguments.py new file mode 100644 index 0000000..65a2350 --- /dev/null +++ b/src/PythonMetaTrader5/legacy/arguments.py @@ -0,0 +1,46 @@ +"""2.x argument conventions translated into 3.x values. + +Split out of broker.py (300-line limit); everything here is pure. +""" + +from __future__ import annotations + +import logging +from typing import Any + +from PythonMetaTrader5.domain.stops import Stop +from PythonMetaTrader5.result import Err, Ok, Result + +log = logging.getLogger("PythonMetaTrader5.legacy") + + +def number(value: Any) -> Any: + """Convert numeric strings with float() as 2.x did, raising on garbage as it did. + + Only strings are converted: float(True) would turn a stray bool into one + lot, so every other type goes on unchanged and is checked by the Trader. + """ + return float(value) if isinstance(value, str) else value + + +def legacy_stop(value: Any, kind: str) -> Result[Stop | None, str]: + if value is None: + return Ok(None) + match (kind or "absolute").lower(): + case "absolute": + return Ok(Stop.at_price(value)) + case "offset": + return Ok(Stop.points(value)) + case other: + # 2.x opened the position with neither SL nor TP here. + log.error("invalid stop type %r (use 'absolute' or 'offset')", other) + return Err(other) + + +def no_ticket(ticket: int | None) -> bool: + if ticket is None: + return True + # 2.x forwarded it as `position` on an opening deal, which on hedging + # accounts turns an opposite-side entry into a close of that position. + log.error("the ticket argument is not supported for entries; use Close(ticket=...)") + return False diff --git a/src/PythonMetaTrader5/legacy/broker.py b/src/PythonMetaTrader5/legacy/broker.py index d67e68c..28fed61 100644 --- a/src/PythonMetaTrader5/legacy/broker.py +++ b/src/PythonMetaTrader5/legacy/broker.py @@ -18,8 +18,9 @@ from PythonMetaTrader5.domain.errors import TradeError from PythonMetaTrader5.domain.market import PendingKind, TradeReceipt from PythonMetaTrader5.domain.orders import Side -from PythonMetaTrader5.domain.stops import Stop from PythonMetaTrader5.legacy import views +from PythonMetaTrader5.legacy.arguments import legacy_stop, no_ticket, number +from PythonMetaTrader5.legacy.views import LegacyReceipt from PythonMetaTrader5.result import Err, Ok, Result log = logging.getLogger("PythonMetaTrader5.legacy") @@ -89,7 +90,8 @@ def GetPositions( trader = self._ready() if trader is None: return [] - listed = trader.positions(symbol, ticket=ticket) + # 2.x: a ticket selects that position whatever symbol was passed. + listed = trader.positions(None if ticket is not None else symbol, ticket=ticket) if isinstance(listed, Err): log.error("%s: %s", self.log, listed.error) return [] @@ -117,16 +119,22 @@ def OpenPosition( ticket: int | None = None, sl_type: str = "absolute", tp_type: str = "absolute", - ) -> TradeReceipt | None: + ) -> LegacyReceipt | None: trader = self._ready() - if trader is None or not _no_ticket(ticket): + if trader is None or not no_ticket(ticket): return None - stops = _legacy_stop(sl, sl_type), _legacy_stop(tp, tp_type) + stops = legacy_stop(number(sl), sl_type), legacy_stop(number(tp), tp_type) if any(isinstance(stop, Err) for stop in stops): return None stop_loss, take_profit = (s.value for s in stops if isinstance(s, Ok)) result = trader.open_position( - symbol, side, volume, sl=stop_loss, tp=take_profit, price=price, comment=comment + symbol, + side, + number(volume), + sl=stop_loss, + tp=take_profit, + price=number(price), + comment=comment, ) return self._receipt(result, f"{side} {symbol}") @@ -154,7 +162,7 @@ def BuyLimit( price: float | None = None, comment: str | None = None, ticket: int | None = None, - ) -> TradeReceipt | None: + ) -> LegacyReceipt | None: return self._limit( Side.BUY, symbol, volume, stoplimit, price=price, comment=comment, ticket=ticket ) @@ -167,7 +175,7 @@ def SellLimit( price: float | None = None, comment: str | None = None, ticket: int | None = None, - ) -> TradeReceipt | None: + ) -> LegacyReceipt | None: return self._limit( Side.SELL, symbol, volume, stoplimit, price=price, comment=comment, ticket=ticket ) @@ -224,10 +232,11 @@ def _limit( price: float | None, comment: str | None, ticket: int | None, - ) -> TradeReceipt | None: + ) -> LegacyReceipt | None: trader = self._ready() - if trader is None or self._terminal is None or not _no_ticket(ticket): + if trader is None or self._terminal is None or not no_ticket(ticket): return None + volume, stoplimit = number(volume), number(stoplimit) if price is not None: log.error("%s: price has to be None for limit orders", self.log) return None @@ -250,34 +259,12 @@ def _ready(self) -> Trader | None: return None return self._trader - def _receipt(self, result: Result[TradeReceipt, TradeError], what: str) -> TradeReceipt | None: + def _receipt(self, result: Result[TradeReceipt, TradeError], what: str) -> LegacyReceipt | None: if isinstance(result, Ok): log.info("%s: %s done", self.log, what) - return result.value + return views.as_receipt(result.value) log.error("%s: %s failed: %s", self.log, what, result.error) - return result.error.receipt - - -def _legacy_stop(value: float | None, kind: str) -> Result[Stop | None, str]: - if value is None: - return Ok(None) - match (kind or "absolute").lower(): - case "absolute": - return Ok(Stop.at_price(value)) - case "offset": - return Ok(Stop.points(value)) - case other: - log.error("invalid stop type %r (use 'absolute' or 'offset')", other) - return Err(other) - - -def _no_ticket(ticket: int | None) -> bool: - if ticket is None: - return True - # 2.x forwarded it as `position` on an opening deal, which on hedging - # accounts turns an opposite-side entry into a close of that position. - log.error("the ticket argument is not supported for entries; use Close(ticket=...)") - return False + return views.as_receipt(result.error.receipt) def _load_terminal() -> Terminal | None: diff --git a/src/PythonMetaTrader5/legacy/views.py b/src/PythonMetaTrader5/legacy/views.py index bf2e083..d24746d 100644 --- a/src/PythonMetaTrader5/legacy/views.py +++ b/src/PythonMetaTrader5/legacy/views.py @@ -1,51 +1,121 @@ -"""Positions in the exact shapes the 2.x API returned.""" +"""Positions and receipts in the exact shapes the 2.x API returned. + +2.x handed out raw MetaTrader5 objects (TradePosition, OrderSendResult), so +scripts read any field, index them and call ``_asdict()``. NamedTuples with the +same field names in the same order keep all three working. +""" from __future__ import annotations from typing import Any, NamedTuple -from PythonMetaTrader5.domain.market import Position +from PythonMetaTrader5.domain.market import Position, TradeReceipt from PythonMetaTrader5.domain.orders import Side # MT5 POSITION_TYPE_BUY / POSITION_TYPE_SELL: 2.x callers compare `p.type == 0`. _POSITION_TYPE = {Side.BUY: 0, Side.SELL: 1} +# The keys 2.x `as_dict=True` built by hand; it never exposed the other fields. +_V2_DICT_KEYS = ( + "ticket", + "symbol", + "type", + "volume", + "price_open", + "sl", + "tp", + "price_current", + "profit", + "time", + "magic", + "comment", +) + class LegacyPosition(NamedTuple): - """Attribute-compatible with MT5's TradePosition for the fields 2.x documented.""" + """Field-for-field and in order the same as MetaTrader5.TradePosition.""" ticket: int - symbol: str + time: int + time_msc: int + time_update: int + time_update_msc: int type: int + magic: int + identifier: int + reason: int volume: float price_open: float sl: float tp: float price_current: float + swap: float profit: float - time: int - magic: int + symbol: str comment: str + external_id: str + + +class LegacyReceipt(NamedTuple): + """Field-for-field and in order the same as MetaTrader5.OrderSendResult.""" + + retcode: int + deal: int + order: int + volume: float + price: float + bid: float + ask: float + comment: str + request_id: int + retcode_external: int + # The echoed TradeRequest is not kept by 3.x; always None. + request: None = None def as_object(p: Position) -> LegacyPosition: - # Raw MT5 objects report a missing stop as 0.0; 2.x passed them through as is. return LegacyPosition( - p.ticket, - p.symbol, - _POSITION_TYPE[p.side], - p.volume, - p.price_open, - p.sl or 0.0, - p.tp or 0.0, - p.price_current, - p.profit, - p.time, - p.magic, - p.comment, + ticket=p.ticket, + time=p.time, + time_msc=p.time_msc, + time_update=p.time_update, + time_update_msc=p.time_update_msc, + type=_POSITION_TYPE[p.side], + magic=p.magic, + identifier=p.identifier, + reason=p.reason, + volume=p.volume, + price_open=p.price_open, + # Raw MT5 objects report a missing stop as 0.0; 2.x passed them through as is. + sl=p.sl or 0.0, + tp=p.tp or 0.0, + price_current=p.price_current, + swap=p.swap, + profit=p.profit, + symbol=p.symbol, + comment=p.comment, + external_id=p.external_id, ) def as_dict(p: Position) -> dict[str, Any]: + row = as_object(p)._asdict() # 2.x `as_dict=True` used None for a missing stop, unlike the raw objects. - return {**as_object(p)._asdict(), "sl": p.sl, "tp": p.tp} + return {key: row[key] for key in _V2_DICT_KEYS} | {"sl": p.sl, "tp": p.tp} + + +def as_receipt(receipt: TradeReceipt | None) -> LegacyReceipt | None: + if receipt is None: + return None + return LegacyReceipt( + retcode=receipt.retcode, + deal=receipt.deal, + order=receipt.order, + volume=receipt.volume, + price=receipt.price, + bid=receipt.bid, + ask=receipt.ask, + comment=receipt.comment, + request_id=receipt.request_id, + retcode_external=receipt.retcode_external, + ) diff --git a/tests/unit/fake_mt5.py b/tests/unit/fake_mt5.py index cb0e4e2..9387723 100644 --- a/tests/unit/fake_mt5.py +++ b/tests/unit/fake_mt5.py @@ -56,6 +56,7 @@ def __init__(self) -> None: ask=1.2, comment="Request executed", request_id=13, + retcode_external=0, ) self.positions: tuple[SimpleNamespace, ...] | None = () self.orders: tuple[SimpleNamespace, ...] | None = () @@ -125,6 +126,13 @@ def raw_position(ticket: int = 1, type_: int = 1, sl: float = 0.0) -> SimpleName time=1700000000, magic=42, comment="bot", + swap=-0.5, + identifier=ticket, + reason=3, + time_msc=1700000000123, + time_update=1700000001, + time_update_msc=1700000001456, + external_id="", ) diff --git a/tests/unit/fakes.py b/tests/unit/fakes.py index efd6eae..8f723a7 100644 --- a/tests/unit/fakes.py +++ b/tests/unit/fakes.py @@ -52,6 +52,13 @@ def make_position(ticket: int = 1, **overrides: Any) -> Position: "time": 0, "magic": 0, "comment": "", + "swap": 0.0, + "identifier": ticket, + "reason": 0, + "time_msc": 0, + "time_update": 0, + "time_update_msc": 0, + "external_id": "", } return Position(**{**fields, **overrides}) @@ -67,6 +74,7 @@ def receipt(retcode: int = 10009, price: float = 0.0) -> TradeReceipt: ask=0.0, comment="", request_id=1, + retcode_external=0, ) diff --git a/tests/unit/test_close_positions.py b/tests/unit/test_close_positions.py index e7adc9e..33e370e 100644 --- a/tests/unit/test_close_positions.py +++ b/tests/unit/test_close_positions.py @@ -6,23 +6,18 @@ from PythonMetaTrader5.domain.requests import OrderRequest from PythonMetaTrader5.result import Err, Ok -from .fakes import FakeTerminal +from .fakes import FakeTerminal, make_position def position(ticket: int, symbol: str, side: Side, magic: int = 42) -> Position: - return Position( - ticket=ticket, + return make_position( + ticket, symbol=symbol, side=side, volume=0.2, price_open=1.0, - sl=None, - tp=None, price_current=1.0, - profit=0.0, - time=0, magic=magic, - comment="", ) diff --git a/tests/unit/test_failure_paths.py b/tests/unit/test_failure_paths.py index 093109d..25dc4d7 100644 --- a/tests/unit/test_failure_paths.py +++ b/tests/unit/test_failure_paths.py @@ -5,27 +5,13 @@ from PythonMetaTrader5.application.trader import Trader from PythonMetaTrader5.domain.errors import ErrorKind, TradeError from PythonMetaTrader5.domain.market import Position -from PythonMetaTrader5.domain.orders import Side from PythonMetaTrader5.result import Err -from .fakes import FakeTerminal, receipt +from .fakes import FakeTerminal, make_position, receipt def btc_position() -> Position: - return Position( - ticket=9, - symbol="BTCUSD", - side=Side.BUY, - volume=0.1, - price_open=1.0, - sl=None, - tp=None, - price_current=1.0, - profit=0.0, - time=0, - magic=0, - comment="", - ) + return make_position(9, symbol="BTCUSD", price_open=1.0, price_current=1.0) @pytest.mark.parametrize("policy", [{"attempts": 0}, {"delay_seconds": -1.0}]) diff --git a/tests/unit/test_legacy_broker.py b/tests/unit/test_legacy_broker.py index 32e11aa..fb3ef68 100644 --- a/tests/unit/test_legacy_broker.py +++ b/tests/unit/test_legacy_broker.py @@ -8,7 +8,7 @@ from PythonMetaTrader5.domain.orders import Side from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest -from .fakes import FakeClock, FakeTerminal +from .fakes import FakeClock, FakeTerminal, make_position @pytest.fixture @@ -22,20 +22,7 @@ def orders(terminal: FakeTerminal) -> list[OrderRequest]: def long_position(ticket: int = 1) -> Position: - return Position( - ticket=ticket, - symbol="EURUSD", - side=Side.BUY, - volume=0.1, - price_open=1.0, - sl=None, - tp=1.2, - price_current=1.0, - profit=3.0, - time=5, - magic=0, - comment="", - ) + return make_position(ticket, price_open=1.0, tp=1.2, price_current=1.0, profit=3.0, time=5) def test_constructor_logs_in_with_string_credentials(terminal: FakeTerminal) -> None: diff --git a/tests/unit/test_legacy_compat.py b/tests/unit/test_legacy_compat.py new file mode 100644 index 0000000..25b5b6d --- /dev/null +++ b/tests/unit/test_legacy_compat.py @@ -0,0 +1,128 @@ +"""2.x returned raw MT5 objects; scripts index them, unpack them and call _asdict().""" + +from __future__ import annotations + +from collections import deque + +import pytest + +from PythonMetaTrader5 import Broker +from PythonMetaTrader5.domain.requests import OrderRequest + +from .fakes import FakeClock, FakeTerminal, make_position + +# Field order of MetaTrader5.TradePosition / OrderSendResult (package 5.0.6231). +MT5_POSITION_FIELDS = ( + "ticket", + "time", + "time_msc", + "time_update", + "time_update_msc", + "type", + "magic", + "identifier", + "reason", + "volume", + "price_open", + "sl", + "tp", + "price_current", + "swap", + "profit", + "symbol", + "comment", + "external_id", +) +MT5_RECEIPT_FIELDS = ( + "retcode", + "deal", + "order", + "volume", + "price", + "bid", + "ask", + "comment", + "request_id", + "retcode_external", + "request", +) +V2_DICT_KEYS = { + "ticket", + "symbol", + "type", + "volume", + "price_open", + "sl", + "tp", + "price_current", + "profit", + "time", + "magic", + "comment", +} + + +@pytest.fixture +def broker(terminal: FakeTerminal) -> Broker: + with pytest.warns(DeprecationWarning, match="connect"): + return Broker(1, "pw", "Demo", terminal=terminal, clock=FakeClock()) + + +def sent_orders(terminal: FakeTerminal) -> list[OrderRequest]: + return [r for r in terminal.sent if isinstance(r, OrderRequest)] + + +def test_positions_carry_every_mt5_field_in_mt5_order( + broker: Broker, terminal: FakeTerminal +) -> None: + terminal.open_positions = [make_position(7, swap=-1.5, identifier=7, reason=3)] + (p,) = broker.GetPositions() + assert p._fields == MT5_POSITION_FIELDS + assert (p.swap, p.identifier, p.reason) == (-1.5, 7, 3) + assert p[0] == 7 # 2.x scripts index the raw tuple + + +def test_as_dict_keeps_exactly_the_2x_keys(broker: Broker, terminal: FakeTerminal) -> None: + terminal.open_positions = [make_position(7, swap=-1.5)] + (row,) = broker.GetPositions(as_dict=True) + assert set(row) == V2_DICT_KEYS + + +def test_entry_returns_an_order_send_result_shaped_receipt( + broker: Broker, terminal: FakeTerminal +) -> None: + receipt = broker.Buy("EURUSD", 0.1) + assert receipt._fields == MT5_RECEIPT_FIELDS + assert receipt[0] == receipt.retcode == 10009 + assert receipt._asdict()["retcode_external"] == 0 + # The original request object is not kept; scripts reading it get None. + assert receipt.request is None + + +def test_a_rejected_entry_returns_the_same_receipt_shape( + broker: Broker, terminal: FakeTerminal +) -> None: + terminal.retcodes = deque([10019]) + receipt = broker.Sell("EURUSD", 0.1) + assert receipt._fields == MT5_RECEIPT_FIELDS + assert receipt.retcode == 10019 + + +def test_numeric_strings_are_converted_as_2x_did(broker: Broker, terminal: FakeTerminal) -> None: + broker.OpenPosition("EURUSD", "buy", "0.1", price="1.10010", sl="1.09", tp="1.2") # type: ignore[arg-type] + broker.BuyLimit("EURUSD", "0.2", "1.05") # type: ignore[arg-type] + market, limit = sent_orders(terminal) + assert (market.volume, market.price, market.sl, market.tp) == (0.1, 1.1001, 1.09, 1.2) + assert (limit.volume, limit.price) == (0.2, 1.05) + + +def test_a_non_numeric_string_raises_as_2x_did(broker: Broker, terminal: FakeTerminal) -> None: + with pytest.raises(ValueError, match="could not convert"): + broker.Buy("EURUSD", "lots") # type: ignore[arg-type] + assert terminal.sent == [] + + +def test_ticket_wins_over_symbol_as_in_2x(broker: Broker, terminal: FakeTerminal) -> None: + terminal.open_positions = [make_position(1)] + (p,) = broker.GetPositions("XAUUSD", ticket=1) + assert (p.ticket, p.symbol) == (1, "EURUSD") diff --git a/tests/unit/test_market.py b/tests/unit/test_market.py index 685b780..456cdde 100644 --- a/tests/unit/test_market.py +++ b/tests/unit/test_market.py @@ -1,6 +1,8 @@ -from PythonMetaTrader5.domain.market import Position, Tick +from PythonMetaTrader5.domain.market import Tick from PythonMetaTrader5.domain.orders import Side +from .fakes import make_position + def test_tick_quotes_the_price_a_side_trades_at() -> None: tick = Tick(bid=1.1, ask=1.2) @@ -11,19 +13,6 @@ def test_tick_quotes_the_price_a_side_trades_at() -> None: def test_position_without_stops_reports_none() -> None: - position = Position( - ticket=7, - symbol="EURUSD", - side=Side.SELL, - volume=0.1, - price_open=1.1, - sl=None, - tp=None, - price_current=1.09, - profit=10.0, - time=0, - magic=0, - comment="", - ) + position = make_position(7, side=Side.SELL, price_current=1.09, profit=10.0) assert position.to_dict()["sl"] is None assert position.to_dict()["side"] == "sell" diff --git a/tests/unit/test_mt5_adapter.py b/tests/unit/test_mt5_adapter.py index 2700e28..4b8cf90 100644 --- a/tests/unit/test_mt5_adapter.py +++ b/tests/unit/test_mt5_adapter.py @@ -180,3 +180,22 @@ def test_listing_distinguishes_empty_from_failure( def test_shutdown_is_forwarded(adapter: MetaTrader5Terminal, mt5: FakeMT5) -> None: adapter.shutdown() assert mt5.calls[-1][0] == "shutdown" + + +def test_positions_and_receipts_keep_every_mt5_field( + adapter: MetaTrader5Terminal, mt5: FakeMT5 +) -> None: + mt5.positions = (raw_position(ticket=4),) + listed = adapter.positions() + assert isinstance(listed, Ok) + (p,) = listed.value + assert (p.swap, p.identifier, p.reason, p.external_id) == (-0.5, 4, 3, "") + assert (p.time_msc, p.time_update, p.time_update_msc) == ( + 1700000000123, + 1700000001, + 1700000001456, + ) + mt5.send_result.retcode_external = 77 # type: ignore[union-attr] + sent = adapter.send(CancelRequest(order=1)) + assert isinstance(sent, Ok) + assert sent.value.retcode_external == 77 diff --git a/tests/unit/test_safety_edges.py b/tests/unit/test_safety_edges.py index 1a1cbe8..6702d63 100644 --- a/tests/unit/test_safety_edges.py +++ b/tests/unit/test_safety_edges.py @@ -17,24 +17,11 @@ from PythonMetaTrader5.result import Err, Ok from .fake_mt5 import FakeMT5, symbol_info -from .fakes import FakeClock, FakeTerminal +from .fakes import FakeClock, FakeTerminal, make_position def position(ticket: int, volume: float = 0.5) -> Position: - return Position( - ticket=ticket, - symbol="EURUSD", - side=Side.BUY, - volume=volume, - price_open=1.0, - sl=None, - tp=None, - price_current=1.0, - profit=0.0, - time=0, - magic=0, - comment="", - ) + return make_position(ticket, volume=volume, price_open=1.0, price_current=1.0) def test_empty_symbol_is_rejected_instead_of_meaning_all( From 56457bc27d17f5953e55e48cd024402ae7a0e065 Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 02:55:28 +0100 Subject: [PATCH 15/28] test: compare fakes with the real MetaTrader5 package, cover login retries The docs/tests review found test gaps that hid or could hide real bugs: - tests/contract checks FakeMT5 constants, the fake result rows and the legacy NamedTuples against the installed MetaTrader5 package (values, field names and order). They sit outside tests/unit because the autouse fixture there swaps the module for FakeMT5. The Windows CI job ran the same faked unit tests as Ubuntu; it now runs these against the real wheel. Shown to fail by setting ORDER_FILLING_RETURN to 3 in the fake. - login(ToEffect=True) never looped in any test (FakeTerminal could not fail N times, then succeed); it now has connect_failures and a test. - Broker without an injected terminal (the production path) is covered. - Weak asserts tightened: - The password check used the one-letter password "p". - A positions() magic filter was checked on an empty list. - CancelOrders() "is None" was always true. - A test name claimed a recovery the fake cannot model. - The ci.yml comment on the Windows job now says what it proves. --- .github/workflows/ci.yml | 6 +++-- tests/contract/__init__.py | 0 tests/contract/test_mt5_contract.py | 42 +++++++++++++++++++++++++++++ tests/unit/fakes.py | 5 ++++ tests/unit/test_confirmation.py | 2 +- tests/unit/test_legacy_broker.py | 21 +++++++++++++++ tests/unit/test_legacy_failures.py | 4 ++- tests/unit/test_mt5_adapter.py | 4 +-- tests/unit/test_pending_orders.py | 7 +++-- 9 files changed, 83 insertions(+), 8 deletions(-) create mode 100644 tests/contract/__init__.py create mode 100644 tests/contract/test_mt5_contract.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7cc6d8f..8e4bb4a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -33,8 +33,10 @@ jobs: - run: pytest --cov --cov-report=term-missing windows-mt5: - # The real MetaTrader5 wheel exists only on Windows; this proves the adapter - # matches the constants of the installed package, not just our fake. + # The real MetaTrader5 wheel exists only on Windows. The adapter is built + # against it, and tests/contract compares the unit-test fakes with it + # (constant values, result field names); elsewhere those tests skip. + # Unit tests here still use the fakes, and no terminal is started. name: real MetaTrader5 package (Windows) runs-on: windows-latest steps: diff --git a/tests/contract/__init__.py b/tests/contract/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/contract/test_mt5_contract.py b/tests/contract/test_mt5_contract.py new file mode 100644 index 0000000..2abd5c7 --- /dev/null +++ b/tests/contract/test_mt5_contract.py @@ -0,0 +1,42 @@ +"""The unit-test fakes must look like the real MetaTrader5 package. + +Kept outside tests/unit on purpose: the autouse fixture there replaces the +module with FakeMT5, which would make this a comparison of the fake with +itself. Skipped where the package is not installed (it exists only on +Windows); the Windows CI job runs it against the real wheel. +""" + +from __future__ import annotations + +import re +from typing import Any + +import pytest + +from PythonMetaTrader5.legacy.views import LegacyPosition, LegacyReceipt +from tests.unit.fake_mt5 import CONSTANTS, FakeMT5, raw_order, raw_position, symbol_info + +mt5 = pytest.importorskip("MetaTrader5") + + +def fields(structseq: Any) -> tuple[str, ...]: + # The package's result types are C struct sequences without `_fields`; the + # repr of a filled instance lists the names in order. + sample = structseq(tuple(range(structseq.n_fields))) + return tuple(re.findall(r"(\w+)=", repr(sample))) + + +def test_fake_constants_have_the_real_values() -> None: + assert {name: getattr(mt5, name) for name in CONSTANTS} == CONSTANTS + + +def test_legacy_shapes_match_the_real_result_types() -> None: + assert LegacyPosition._fields == fields(mt5.TradePosition) + assert LegacyReceipt._fields == fields(mt5.OrderSendResult) + + +def test_fake_rows_only_use_fields_the_real_objects_have() -> None: + assert set(vars(raw_position())) == set(fields(mt5.TradePosition)) + assert set(vars(FakeMT5().send_result)) == set(fields(mt5.OrderSendResult)) - {"request"} + assert set(vars(raw_order())) <= set(fields(mt5.TradeOrder)) + assert set(vars(symbol_info())) <= set(fields(mt5.SymbolInfo)) diff --git a/tests/unit/fakes.py b/tests/unit/fakes.py index 8f723a7..0a6acb0 100644 --- a/tests/unit/fakes.py +++ b/tests/unit/fakes.py @@ -89,6 +89,8 @@ class FakeTerminal: open_orders: list[PendingOrder] = field(default_factory=list) send_failure: TradeError | None = None connect_failure: TradeError | None = None + # Number of connect() calls that fail before logins start to work. + connect_failures: int = 0 sent: list[OrderRequest | CancelRequest] = field(default_factory=list) connected_with: list[Credentials] = field(default_factory=list) symbol_lookups: list[str] = field(default_factory=list) @@ -101,6 +103,9 @@ def quote(self, symbol: str, *ticks: tuple[float, float]) -> None: def connect(self, credentials: Credentials) -> Result[None, TradeError]: self.connected_with.append(credentials) + if self.connect_failures: + self.connect_failures -= 1 + return Err(TradeError(ErrorKind.CONNECTION_FAILED, "terminal not ready")) return Err(self.connect_failure) if self.connect_failure else Ok(None) def shutdown(self) -> None: diff --git a/tests/unit/test_confirmation.py b/tests/unit/test_confirmation.py index f413c32..5a75717 100644 --- a/tests/unit/test_confirmation.py +++ b/tests/unit/test_confirmation.py @@ -64,7 +64,7 @@ def test_legacy_broker_rejects_logins_it_would_coerce(login: object) -> None: Broker(login, "pw", "Demo", terminal=FakeTerminal(), clock=FakeClock()) # type: ignore[arg-type] -def test_failed_relogin_releases_the_session_so_a_retry_can_recover() -> None: +def test_failed_relogin_releases_the_session() -> None: mt5 = FakeMT5() adapter = MetaTrader5Terminal(mt5) assert adapter.connect(Credentials(1, "pw", "s")) == Ok(None) diff --git a/tests/unit/test_legacy_broker.py b/tests/unit/test_legacy_broker.py index fb3ef68..dcfc351 100644 --- a/tests/unit/test_legacy_broker.py +++ b/tests/unit/test_legacy_broker.py @@ -8,6 +8,7 @@ from PythonMetaTrader5.domain.orders import Side from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest +from .fake_mt5 import FakeMT5, raw_position from .fakes import FakeClock, FakeTerminal, make_position @@ -142,3 +143,23 @@ def pending(ticket: int, kind: PendingKind) -> PendingOrder: def test_disconnect_shuts_the_terminal_down(broker: Broker, terminal: FakeTerminal) -> None: broker.Disconnect() assert terminal.shut_down + + +def test_login_with_to_effect_keeps_trying_until_it_works( + broker: Broker, terminal: FakeTerminal, clock: FakeClock +) -> None: + terminal.connect_failures = 2 + before = len(terminal.connected_with) + assert broker.login(ToEffect=True) is True + assert len(terminal.connected_with) - before == 3 + assert clock.sleeps[-2:] == [1.0, 1.0] + + +def test_broker_without_an_injected_terminal_uses_the_metatrader5_module( + no_real_terminal: FakeMT5, +) -> None: + no_real_terminal.positions = (raw_position(ticket=8),) + with pytest.warns(DeprecationWarning, match="connect"): + broker = Broker(1, "pw", "Demo", clock=FakeClock()) + assert [p.ticket for p in broker.GetPositions()] == [8] + assert no_real_terminal.calls[0][0] == "initialize" diff --git a/tests/unit/test_legacy_failures.py b/tests/unit/test_legacy_failures.py index 2e6b1cb..a047235 100644 --- a/tests/unit/test_legacy_failures.py +++ b/tests/unit/test_legacy_failures.py @@ -21,7 +21,9 @@ def test_without_metatrader5_package_every_call_is_a_logged_no_op( assert broker.GetPositions() == [] assert broker.Close("EURUSD") is False assert broker.BuyLimit("EURUSD", 0.1, 1.0) is None - assert broker.CancelOrders("EURUSD") is None + caplog.clear() + broker.CancelOrders("EURUSD") + assert "not connected" in caplog.text broker.Disconnect() assert "not connected" in caplog.text diff --git a/tests/unit/test_mt5_adapter.py b/tests/unit/test_mt5_adapter.py index 4b8cf90..ecb7184 100644 --- a/tests/unit/test_mt5_adapter.py +++ b/tests/unit/test_mt5_adapter.py @@ -42,11 +42,11 @@ def test_connect_passes_credentials_and_reports_failure( {"login": 123, "password": "secret", "server": "Demo", "timeout": 5000}, ) mt5.initialize_ok, mt5.error = False, (-6, "Authorization failed") - result = adapter.connect(Credentials(1, "p", "s", path="C:/mt5/terminal64.exe")) + result = adapter.connect(Credentials(1, "hunter2-pw", "s", path="C:/mt5/terminal64.exe")) assert isinstance(result, Err) assert result.error.kind is ErrorKind.CONNECTION_FAILED assert "Authorization failed" in result.error.message - assert "p" not in result.error.message.split() + assert "hunter2" not in result.error.message assert mt5.calls[-2][1] == ("C:/mt5/terminal64.exe",) assert mt5.calls[-1][0] == "shutdown" diff --git a/tests/unit/test_pending_orders.py b/tests/unit/test_pending_orders.py index e79d93a..03c9cb5 100644 --- a/tests/unit/test_pending_orders.py +++ b/tests/unit/test_pending_orders.py @@ -7,7 +7,7 @@ from PythonMetaTrader5.domain.symbol import Filling from PythonMetaTrader5.result import Err, Ok -from .fakes import FakeTerminal +from .fakes import FakeTerminal, make_position def test_limit_order_is_placed_at_its_level(trader: Trader, terminal: FakeTerminal) -> None: @@ -60,7 +60,10 @@ def test_queries_filter_by_magic(trader: Trader, terminal: FakeTerminal) -> None pending = trader.pending_orders(magic=1) assert isinstance(pending, Ok) assert [o.ticket for o in pending.value] == [7] - assert trader.positions("EURUSD") == Ok([]) + terminal.open_positions = [make_position(1, magic=1), make_position(2, magic=0)] + positions = trader.positions("EURUSD", magic=1) + assert isinstance(positions, Ok) + assert [p.ticket for p in positions.value] == [1] def test_shutdown_releases_the_terminal(trader: Trader, terminal: FakeTerminal) -> None: From 4546b051891595b9172c645e0f348b5ef80104eb Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 02:57:38 +0100 Subject: [PATCH 16/28] docs: list every 2.x behaviour change, fix stale and wrong claims, ADR 0008-0009 Docs fixes found by the independent reviews: - CHANGELOG said a failed re-login keeps a working session. bc237d4 reversed that, and the entry was never updated. - MIGRATION said invalid input returns "the receipt". It returns None, because nothing was sent. - MIGRATION said GetPositions has "the same fields". It now does, and the entry says so precisely. - The MIGRATION example `[p.to_dict() for p in trader.positions().value]` raised on Err. It now matches on Ok/Err and notes `side` vs `type`. - README said BatchFailure.succeeded shows "exactly which tickets closed". The receipts carry deal/order IDs, not position tickets. - README and ADR 0003 said "every call returns". Broker.login(ToEffect=True) loops by design, and batches take the time limit per position. - architecture.md said legacy works "through Trader and ports". It builds the default adapters itself. MIGRATION gains the behaviour changes that were missing: - failed logins disable the Broker, and one shared session per process; - invalid input is refused before sending; - sl=0 and unknown sl_type (2.x opened with no SL and no TP); - volume=True; - offset stops with an explicit price, including the market-execution case; - Close() no longer loops, so a Close-then-Buy reversal must check the result; - ticket=0; - receipt and position shapes; - the time/logger/pyautogui star exports; - DeprecationWarning under -W error; - limit-order filling. ADR 0008 records why such inputs are refused. ADR 0009 records why the terminal lock is per process, not per adapter. --- CHANGELOG.md | 21 ++++-- MIGRATION.md | 76 +++++++++++++++++---- README.md | 26 +++++-- docs/adr/0003-bounded-retries.md | 5 +- docs/adr/0006-legacy-facade.md | 3 + docs/adr/0008-refuse-values-mt5-misreads.md | 42 ++++++++++++ docs/adr/0009-one-lock-per-process.md | 31 +++++++++ docs/architecture.md | 22 ++++-- 8 files changed, 195 insertions(+), 31 deletions(-) create mode 100644 docs/adr/0008-refuse-values-mt5-misreads.md create mode 100644 docs/adr/0009-one-lock-per-process.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 21e83ff..fa7e5f6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,9 +21,16 @@ Complete rewrite. See [MIGRATION.md](MIGRATION.md) for every behaviour change. - CI: ruff, mypy --strict, tests on Python 3.10-3.14, a Windows job against the real `MetaTrader5` package, Semgrep, a 300-line file limit, build checks. - Integration tests against a demo account. +- Contract tests comparing the unit-test fakes with the real `MetaTrader5` + package (run by the Windows CI job). +- Thread safety: every terminal call holds one process-wide lock. ### Changed -- `Broker` is a deprecated facade over `Trader` with the 2.x method names. +- `Broker` is a deprecated facade over `Trader` with the 2.x method names. It + returns `LegacyPosition` / `LegacyReceipt` named tuples with the fields and + field order of MT5's `TradePosition` / `OrderSendResult`. +- `Position` carries every `TradePosition` field (`swap`, `identifier`, ...); + `TradeReceipt` gains `retcode_external`. - Bounded retries (requotes only) instead of endless loops. - Prices snap to the symbol's tick size instead of rounding to `digits`. - Logging moved from `loguru` to the standard `logging` module. @@ -32,7 +39,8 @@ Complete rewrite. See [MIGRATION.md](MIGRATION.md) for every behaviour change. ### Removed - `pyautogui` Ctrl+E hotkey on retcode 10027. -- The `from MetaTrader5 import *` re-export. +- The `import *` re-exports of `MetaTrader5`, `time`, loguru's `logger` and + `pyautogui`. - The `Broker.password` attribute. ### Safety @@ -44,8 +52,13 @@ Complete rewrite. See [MIGRATION.md](MIGRATION.md) for every behaviour change. re-sent. - Logins that would be coerced (`True`, `12345678.9`, non-ASCII digits) are rejected, in `connect()` and in `Broker`. -- A failed first login shuts the half-open terminal session down; a failed - re-login keeps an already working session. +- Every failed login shuts the terminal session down, and `Broker` refuses to + trade until a login succeeds. +- `sl=0` / `tp=0`, stops that resolve to zero or below, tickets that are not + positive integers, `volume=True` and non-finite numbers are rejected before + sending. +- `positions(symbol, ticket=...)` applies both filters (MT5 drops the symbol + once a ticket is given). - Pending orders on exchange-execution symbols use RETURN filling. - `Broker.Close(None)` / `Broker.CancelOrders(None)` act on nothing. diff --git a/MIGRATION.md b/MIGRATION.md index 522916c..e679280 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -8,38 +8,72 @@ upgrading a bot that trades real money. - Python **3.10+** (2.x claimed 3.6+). - `pyautogui` and `loguru` are no longer dependencies. +- Creating a `Broker` emits a `DeprecationWarning`. Test suites that run with + `-W error` or pytest's `filterwarnings = error` must allow it, e.g. + `filterwarnings = ["error", "ignore:Broker is deprecated:DeprecationWarning"]`. ## Behaviour changes in `Broker` +### Logging in + +| 2.x | 3.0 | Why | +|---|---|---| +| The constructor called `initialize()` without credentials, then `login()`. After a failed login it went on trading on whichever account the terminal had open | A failed login shuts the terminal session down. Every method then returns `None` / `[]` / `False` and logs "not connected" until `login()` succeeds | Orders went to an account nobody asked for | +| A failed `login()` (for example as a health check) left the working session alone | A failed `login()` also shuts the session down and disables the `Broker` until a login works | After a failed login MT5's single per-process session can be left half-open, so later `initialize()` calls fail | +| Several `Broker` objects in one process each believed they had their own connection | Unchanged, but now visible: MT5 has one session per process, so one instance's failed login disconnects the others too | Run one process per account | +| `Broker(True, ...)` or `Broker(12345678.9, ...)` logged into account 1 / 12345678 | Raises `ValueError` (as a non-numeric login already did) | It traded on a different account than intended | + +### Opening positions and limit orders + | 2.x | 3.0 | Why | |---|---|---| -| `OpenPosition`, `BuyLimit`, `SellLimit` retried **forever** on any unknown retcode (e.g. no money, invalid volume, market closed over the weekend), sending an order every 0.5 s | Requotes retried at most 3 times; every other failure returns at once (the receipt is returned, the error is logged) | A weekend webhook would block the bot until Monday; a rejected order was re-sent indefinitely | +| `OpenPosition`, `Buy*`, `Sell*`, `BuyLimit`, `SellLimit` retried **forever** on any unknown retcode (no money, invalid volume, market closed over the weekend), sending an order every 0.5 s | Requotes are retried at most 3 times. Any other broker refusal returns at once: the receipt is returned and the error is logged | A weekend webhook blocked the bot until Monday; a rejected order was re-sent indefinitely | +| Invalid input was sent anyway and then retried forever | Refused **before sending**: the call returns `None`, not a receipt, and logs why. This covers a volume off the lot step or outside min/max, an unknown symbol, a comment over 31 characters, and the cases below. Check for `None` before reading `.retcode` | Nothing was sent, so there is no broker answer to return | +| `sl=0` / `tp=0` sent 0.0, which MT5 reads as "no stop" | Refused (returns `None`). Pass `None`, or leave the argument out, for no stop | A missing SL field in a webhook opened an unprotected position without any error | +| An unknown `sl_type` / `tp_type` (e.g. `"bogus"`) opened the position with **neither SL nor TP** | Opens nothing, returns `None` and logs the error | The stop the caller asked for was silently dropped | +| `volume=True` was traded as 1 lot; NaN or infinite numbers crashed deep inside | Refused (returns `None`). Numeric strings (`"0.1"`) are still converted as in 2.x | A stray bool must not become one lot | +| `sl_type="offset"` with an explicit `price=` was measured from the live quote | Measured from `price`. With instant execution the order fills only within `deviation` of `price`, so this is a few points at most. With market execution the broker ignores `price` and fills at the market, so a stale `price` moves the stops by the same distance. A stop that lands on the wrong side of the market is rejected by the server (10016), not applied | The stops follow the price the caller asked for. Use absolute stops if they must not depend on `price` | | On retcode 10027 it pressed **Ctrl+E** via `pyautogui` | Logs "enable Algo Trading" and returns the receipt | Ctrl+E *toggles* Algo Trading and is typed into whichever window has focus | +| A partial or only-queued (PLACED) market entry counted as opened | Logged as an error; the receipt is still returned, so check `receipt.retcode` (10009 = done) | The bot believed it held the full size | +| Retcode 10008 (`PLACED`) for limit orders was treated as failure and re-sent | Treated as success | Limit orders could be placed more than once | +| `ticket=` on `OpenPosition`/`Buy`/`Sell`/`BuyLimit`/`SellLimit` was forwarded as `position` | Refused: returns `None`, logs an error | On hedging accounts it turned an entry into a close of that position | +| Comments longer than 31 characters made `order_send` fail with `None` | Rejected before sending, logged | Explicit error instead of a crash downstream | +| Prices rounded to `digits` | Prices snapped to the symbol's tick size | Symbols with tick 0.25 were rejected | +| Fixed filling: FOK for market entries, IOC for closes and limit orders | Filling chosen from the symbol's allowed modes (FOK > IOC > RETURN); limit orders on exchange-execution symbols use RETURN | Brokers without FOK rejected every order (10030); IOC cancelled exchange limits unless instantly fillable | + +### Closing and cancelling + +| 2.x | 3.0 | Why | +|---|---|---| +| `Close()` looped until every position closed, e.g. through a whole closed-market weekend | One attempt per position (requotes retried up to 3 times); a failure returns `False`. A reversal written as `Close(s); Buy(s, v)` must check that `Close` returned `True`, or it may end up holding both | Same as the endless entry loop | | `Close()` always returned `False` | `True` if at least one position closed and none failed, else `False` | The return value was meaningless | | `Close(symbol=None, ticket=...)` crashed | Each position is closed on its own symbol | It priced the close with the `symbol` argument | | `Close(None)` without a ticket crashed without closing anything | Still closes nothing: logs an error, returns `False` | Forwarding `None` would close every position on the account | +| `Close(ticket=0)` / `GetPositions(ticket=0)` passed 0 to `positions_get` | Refused: `False` / `[]`, error logged | 0 may mean "no filter" and close the whole account | | A partly filled close counted as closed | Reported as a failure (`PARTIAL_FILL`), `Close()` returns `False` | The rest of the position was left open silently | -| A partial or only-queued (PLACED) market entry counted as opened | Logged as an error; the receipt is still returned, so check `receipt.retcode` (10009 = done) | The bot believed it held the full size | | `CancelOrders(None)` | Cancels nothing and logs an error | Guards against a missing symbol acting on the whole account | -| `Broker(True, ...)` or `Broker(12345678.9, ...)` logged into account 1 / 12345678 | Raises `ValueError` (as a non-numeric login already did) | It traded on a different account than intended | -| Limit orders on exchange-execution symbols used IOC | Use RETURN so they rest in the book | IOC cancelled them unless instantly fillable | | `CancelOrders` could loop forever on a failed cancel | One attempt per order (requotes retried), failures logged | Same as above | -| Comments longer than 31 characters made `order_send` fail with `None` | Rejected before sending, logged | Explicit error instead of a crash downstream | -| `ticket=` on `OpenPosition`/`Buy`/`Sell`/`BuyLimit`/`SellLimit` was forwarded as `position` | Refused: returns `None`, logs an error | On hedging accounts it turned an entry into a close of that position | -| Retcode 10008 (`PLACED`) for limit orders was treated as failure and re-sent | Treated as success | Limit orders could be placed more than once | -| Prices rounded to `digits` | Prices snapped to the symbol's tick size | Symbols with tick 0.25 were rejected | -| Fixed FOK (open) / IOC (close) filling | Filling chosen from the symbol's allowed modes (FOK > IOC > RETURN) | Brokers without FOK rejected every order (10030) | + +### Returned objects + +| 2.x | 3.0 | Why | +|---|---|---| +| Entries returned MT5's raw `OrderSendResult` | A `LegacyReceipt` named tuple with the same fields in the same order: attribute access, indexing and `_asdict()` work. `request` is always `None` | 3.x does not keep the echoed request | +| `GetPositions()` returned raw MT5 `TradePosition` objects | `LegacyPosition` named tuples with every `TradePosition` field in MT5's order; `as_dict=True` returns the same 12 keys as before | No dependency on MT5 internals | | `broker.password` attribute | Removed; credentials are kept in a non-printing object | The password showed up in debug dumps | -| `GetPositions()` returned raw MT5 objects | Returns `LegacyPosition` named tuples with the same fields (`ticket`, `type`, `sl`, ...) | Same attribute access; no dependency on MT5 internals | -## Removed: `from MetaTrader5 import *` re-export +## Removed: the `import *` re-exports -2.x re-exported the whole `MetaTrader5` namespace, so -`from PythonMetaTrader5 import *` also gave you `symbol_info`, `ORDER_TYPE_BUY` -and friends. Import those from the official package instead: +2.x re-exported the whole `MetaTrader5` namespace plus the modules it used +itself. `from PythonMetaTrader5 import *` therefore also gave you +`symbol_info`, `ORDER_TYPE_BUY` and friends, and `time`, `logger` (loguru) and +`pyautogui`. None of these come through any more. Import them yourself: ```python +import time + import MetaTrader5 as mt5 + info = mt5.symbol_info("EURUSD") ``` @@ -51,6 +85,7 @@ configuration; to see info messages: ```python import logging + logging.basicConfig(level=logging.INFO) ``` @@ -64,5 +99,16 @@ logging.basicConfig(level=logging.INFO) | `Close("EURUSD")` | `trader.close_positions("EURUSD")` | | `BuyLimit(s, v, stoplimit=1.1)` | `trader.place_limit_order(s, "buy", v, 1.1)` (no automatic market fill when crossed) | | `CancelOrders(s)` | `trader.cancel_pending_orders(s, kind=PendingKind.LIMIT)` | -| `GetPositions(as_dict=True)` | `[p.to_dict() for p in trader.positions().value]` | +| `GetPositions(as_dict=True)` | see below | | `Disconnect()` | `trader.shutdown()` or `with trader:` | + +`positions()` returns a `Result`, and its dictionaries use `side: "buy"` / +`"sell"` instead of the numeric `type`: + +```python +match trader.positions(): + case Ok(positions): + rows = [p.to_dict() for p in positions] + case Err(error): + print("cannot list positions:", error) +``` diff --git a/README.md b/README.md index c20efe3..1a62dfc 100644 --- a/README.md +++ b/README.md @@ -13,8 +13,13 @@ A safe, typed trading layer over the official Built for bots (webhook executors, signal followers) where a trading call must **never hang, never retry blindly, and never fail silently**: -- **Every call returns.** Requotes are retried a bounded number of times with a - fresh quote; everything else comes back immediately as a typed error. +- **Every trading call returns.** Requotes are retried a bounded number of times + with a fresh quote; everything else comes back immediately as a typed error. + (The deprecated `Broker.login(ToEffect=True)` is the one exception: as in + 2.x, it keeps trying until the login works.) +- **No silent defaults.** Values that MT5 would quietly read as something else + are refused before sending: `sl=0` ("no stop"), `ticket=0` (possibly "no + filter"), `volume=True` (one lot), NaN and infinities. - **No double fills.** Timeouts and lost connections are never auto-retried: the order may already be live. - **Typed results.** `Ok(receipt)` or `Err(TradeError)` with an `ErrorKind` @@ -29,6 +34,10 @@ Built for bots (webhook executors, signal followers) where a trading call must > terminal session, so a second `connect()` (or its failed login) affects the > first. Run one process per account. > +> Thread-safe within the library: every terminal call holds one process-wide +> lock, so a threaded webhook server can share a `Trader`. Calls you make to +> the `MetaTrader5` module directly bypass that lock. +> > Requires Windows with a MetaTrader 5 terminal installed (the official > `MetaTrader5` package is Windows-only). Enable **Algo Trading** in the terminal. @@ -86,15 +95,20 @@ deviation=10, retry=None) -> Result[Trader, TradeError]` - `side`: `Side.BUY` / `Side.SELL`, or the strings `"buy"`, `"sell"`, `"long"`, `"short"`. - `sl` / `tp`: a float is an **absolute price**; `Stop.points(n)` is a distance of `n` points from the entry price (`Stop.at_price(p)` is the explicit form). - For limit orders the distance is measured from the limit price. + For limit orders the distance is measured from the limit price, and for a + market order with an explicit `price` from that price. Zero, negative and + non-finite stops are rejected (`INVALID_STOPS`); pass `None` for no stop. - `price` (market orders): send at this price once instead of the live quote. - `comment`: at most 31 characters (the terminal's limit). Longer comments are rejected, not truncated. - **`close_positions()` and `cancel_pending_orders()` without arguments act on the whole account**, including manual trades. A bot should always pass its `magic` (and a symbol); an empty string `""` is rejected. -- `BatchFailure.succeeded` / `.errors` tell exactly which tickets closed and - which did not; each `TradeError.ticket` names the position/order. +- `BatchFailure.errors` names every position/order that failed + (`TradeError.ticket`). `BatchFailure.succeeded` holds the receipts of the + ones that worked; their `order` / `deal` are the IDs of the closing deal, not + the position ticket. +- `ticket` must be a positive integer; `0`, `True` or `"7"` are rejected. ### Errors @@ -139,6 +153,8 @@ mypy pytest --cov ``` +`tests/contract` compares the unit-test fakes with the installed `MetaTrader5` +package and is skipped where it is not installed (anywhere but Windows). Integration tests trade on a **demo** account and are skipped unless `MT5_LOGIN`, `MT5_PASSWORD` and `MT5_SERVER` are set (they refuse to run on a live account): `pytest -m integration`. diff --git a/docs/adr/0003-bounded-retries.md b/docs/adr/0003-bounded-retries.md index 43ba095..04ee7fb 100644 --- a/docs/adr/0003-bounded-retries.md +++ b/docs/adr/0003-bounded-retries.md @@ -37,5 +37,8 @@ For pending orders, PLACED is the normal success. ## Consequences -- Every call returns within `attempts × (delay + round trip)`. +- Every trading request returns within `attempts × (delay + round trip)`; a + batch close or cancel takes that per position or order. The deprecated + `Broker.login(ToEffect=True)` is the exception: it retries until the login + works, because 2.x documented exactly that. - Callers that handle `OUTCOME_UNKNOWN` must reconcile with `positions()`. diff --git a/docs/adr/0006-legacy-facade.md b/docs/adr/0006-legacy-facade.md index d6dba3e..cc9a519 100644 --- a/docs/adr/0006-legacy-facade.md +++ b/docs/adr/0006-legacy-facade.md @@ -25,3 +25,6 @@ every new MT5 symbol part of our public API without any review. - Old scripts keep running. Scripts that relied on re-exported MT5 names must import `MetaTrader5` directly. +- 2.x returned raw MT5 objects, so "the same return shapes" means named + tuples (`LegacyPosition`, `LegacyReceipt`) with MT5's field names and field + order. `tests/contract` checks them against the installed package. diff --git a/docs/adr/0008-refuse-values-mt5-misreads.md b/docs/adr/0008-refuse-values-mt5-misreads.md new file mode 100644 index 0000000..4bf1880 --- /dev/null +++ b/docs/adr/0008-refuse-values-mt5-misreads.md @@ -0,0 +1,42 @@ +# ADR 0008: Refuse input that MT5 would quietly read as something else + +- Status: accepted (3.0.0) + +## Context + +Webhook payloads are loosely typed JSON. Several values that a missing or +malformed field produces have a valid but unintended meaning in MT5: + +- `sl=0` / `tp=0` is "no stop", so the position opens unprotected and the call + reports success. +- `ticket=0` may be read as "no filter" by `positions_get`, which in a close + would close the whole account. +- `volume=True` is the number 1, so it trades one lot. +- NaN and infinities crashed with `ValueError` / `OverflowError` deep inside + price rounding, which broke the "every boundary returns a `Result`" rule. + +The empty symbol `""` was already refused for the same reason. + +## Decision + +Refuse these values at the application boundary, before any terminal call: + +- Volume and prices must be positive finite real numbers. Bools are excluded. + `numbers.Real` is used rather than `float`, so numpy scalars from + pandas-based bots still pass. +- A stop is `None` (no stop), a positive finite price or a `Stop`. A stop that + resolves to zero or below after tick-grid rounding is refused too. +- A ticket is `None` or a positive integer. + +The rules live in `domain/inputs.py` as plain functions, not a port, because +they do no I/O. The legacy `Broker` converts numeric strings with `float()` +first, as 2.x did. It does not convert bools, so `True` is refused there as +well. + +## Consequences + +- 2.x scripts that passed `sl=0` to mean "no stop" now get `None` and an + error log instead of a trade. MIGRATION.md says so, and `None` is the way + to ask for no stop. +- An honest zero-distance stop (`Stop.points(0)`) is refused before sending + instead of being rejected by the server with 10016. diff --git a/docs/adr/0009-one-lock-per-process.md b/docs/adr/0009-one-lock-per-process.md new file mode 100644 index 0000000..3da3d9d --- /dev/null +++ b/docs/adr/0009-one-lock-per-process.md @@ -0,0 +1,31 @@ +# ADR 0009: One lock per process around terminal calls + +- Status: accepted (3.0.0) + +## Context + +After a failed `order_send`, the adapter reads `last_error()` to decide +between `TERMINAL_ERROR` (never sent, safe to resend) and `OUTCOME_UNKNOWN` +(may have reached the server). `last_error()` is process-global. In a threaded +webhook server, thread B's call can overwrite the error before thread A reads +it. A's lost order could then be labelled "never sent", and resending it +would open a duplicate position. + +## Decision + +`adapters/mt5_terminal.py` holds a module-level `threading.RLock`. Every +public adapter method runs under it, so a call and the error read that +explains it are atomic. + +We rejected a lock per adapter. `connect()` builds a new adapter each time, +and every adapter in a process talks to the same global MT5 session, so +separate locks would not exclude each other. + +## Consequences + +- Terminal calls from different threads run one at a time. MT5 serves one + session per process anyway, so no parallelism is lost. +- A slow call (a login waiting for `timeout_ms`) delays the other threads + for that long. +- Calls that user code makes to the `MetaTrader5` module directly are outside + the lock. The README says so. diff --git a/docs/architecture.md b/docs/architecture.md index adc0e3b..990793e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -15,7 +15,7 @@ adapters/ ───────────────┘ ▲ | Application | `application/` | use cases (`Trader`), retry loop, batch reporting, **ports** | only through ports | | Adapters | `adapters/` | the `MetaTrader5` package, `time.sleep` | yes | | Composition | `connection.py` | wires adapters into a `Trader` | through adapters | -| Compatibility | `legacy/` | the 2.x `Broker` API mapped onto `Trader` | through `Trader` and ports | +| Compatibility | `legacy/` | the 2.x `Broker` API mapped onto `Trader` | through `Trader`; builds the default adapters itself when none are injected | ## Ports @@ -30,14 +30,22 @@ volume checks) is plain functions and methods on domain objects, not ports. ## Request flow: `open_position` -1. Validate side, comment, symbol spec and volume. Errors return before any - order is sent. -2. Build the request from the **current** quote (`Tick.entry_price`), resolving - `Stop.points` against that price. +1. Validate side, comment, stops and volume (`domain/inputs.py`: positive, + finite, no bools, no zero stops), then the symbol spec + (`application/entries.py`). Errors return before any order is sent. +2. Build the request from the **current** quote (`Tick.entry_price`), or from + the explicit `price`, resolving `Stop.points` against that price. A stop that + resolves to zero or below is refused. 3. `execute()` sends it and classifies the retcode ([ADR 0003](adr/0003-bounded-retries.md)): success → `Ok`; retryable → sleep and rebuild with a fresh quote; anything else → `Err` with the receipt. +## Concurrency + +`last_error()` in the `MetaTrader5` package is process-global, so the adapter +holds one module-level lock around every terminal call and the error read that +explains it ([ADR 0009](adr/0009-one-lock-per-process.md)). + ## Errors Expected failures travel as `Result` values @@ -48,5 +56,7 @@ programming errors (e.g. `RetryPolicy(attempts=0)`). - `tests/unit`: fakes for both ports (`fakes.py`) and for the `MetaTrader5` module (`fake_mt5.py`); runs on any OS. +- `tests/contract`: the fakes compared with the installed `MetaTrader5` + package (constant values, result field names and order); skipped where the + package is missing. CI runs it on Windows against the real wheel. - `tests/integration`: a real terminal on a demo account, opt-in via `MT5_*`. -- CI also builds the adapter against the real `MetaTrader5` wheel on Windows. From 23f78ffa064ca2df702ceebc9dc437dfbfe018b9 Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 03:02:05 +0100 Subject: [PATCH 17/28] fix: close /code-review high findings on legacy limits, bool stops, Decimal - Legacy BuyLimit/SellLimit compared the raw stoplimit with the quote before any check. SellLimit(s, v, 0) "crossed" and was sent as a market SELL, and inf or True did the same. The level is now checked first. - Stop.at_price()/points() ran float() on their argument, so True became 1.0 before stop_input could refuse it. Broker(..., sl=True) opened with sl=1.0. The factories now store the value unconverted, stop_input checks it and rebuilds the Stop from the checked float, and the sign of a points distance is dropped in Stop._resolve. - Decimal volumes and prices were refused because Decimal is not a numbers.Real. They worked before via float(), so this was a regression from 55be3e2. Decimal is now accepted explicitly. - A bad price was checked after the symbol lookup. That cost a terminal round trip and could add the symbol to Market Watch. It is now checked first. - as_dict builds the 2.x dict straight from Position. _V2_DICT_KEYS is removed; grep over src tests docs finds no other use. - A test-fake comment now states the decision, not the action. Not changed: number() conversion stays at the two legacy entry points (OpenPosition, _limit). Every legacy entry method goes through one of them, so a separate normaliser would be a third place to keep in sync. RED: 7 of the 8 new cases failed before the change. The legacy limit at NaN already returned None, because comparisons with NaN are false. --- docs/adr/0008-refuse-values-mt5-misreads.md | 9 ++++- src/PythonMetaTrader5/application/entries.py | 5 ++- src/PythonMetaTrader5/application/trader.py | 13 ++++--- src/PythonMetaTrader5/domain/inputs.py | 16 +++++--- src/PythonMetaTrader5/domain/stops.py | 15 +++++--- src/PythonMetaTrader5/legacy/broker.py | 12 +++++- src/PythonMetaTrader5/legacy/views.py | 32 +++++++--------- tests/unit/fakes.py | 2 +- tests/unit/test_input_guards.py | 40 ++++++++++++++++++++ 9 files changed, 104 insertions(+), 40 deletions(-) diff --git a/docs/adr/0008-refuse-values-mt5-misreads.md b/docs/adr/0008-refuse-values-mt5-misreads.md index 4bf1880..a0d0050 100644 --- a/docs/adr/0008-refuse-values-mt5-misreads.md +++ b/docs/adr/0008-refuse-values-mt5-misreads.md @@ -23,7 +23,14 @@ Refuse these values at the application boundary, before any terminal call: - Volume and prices must be positive finite real numbers. Bools are excluded. `numbers.Real` is used rather than `float`, so numpy scalars from - pandas-based bots still pass. + pandas-based bots still pass. `Decimal`, which is not a `Real`, is accepted + explicitly. +- `Stop.at_price()` and `Stop.points()` store their argument unconverted. If + they called `float()`, `True` would become `1.0` before the check could see + it. +- The legacy `BuyLimit` / `SellLimit` check the level before comparing it + with the quote. Otherwise a level of 0 would "cross" the market and be sent + as a market order. - A stop is `None` (no stop), a positive finite price or a `Stop`. A stop that resolves to zero or below after tick-grid rounding is refused too. - A ticket is `None` or a positive integer. diff --git a/src/PythonMetaTrader5/application/entries.py b/src/PythonMetaTrader5/application/entries.py index 6435c4e..083e094 100644 --- a/src/PythonMetaTrader5/application/entries.py +++ b/src/PythonMetaTrader5/application/entries.py @@ -69,8 +69,9 @@ def validate_entry( sl: StopInput, tp: StopInput, ) -> Result[Entry, TradeError]: - # Every check that needs no terminal runs first, so bad input never costs a - # symbol lookup (which may add the symbol to Market Watch). + # Every check that needs no terminal runs before the symbol lookup, which + # costs a round trip and may add the symbol to Market Watch. Callers check + # their own price argument before calling this, for the same reason. values = _caller_values(side, comment, sl, tp) if isinstance(values, Err): return values diff --git a/src/PythonMetaTrader5/application/trader.py b/src/PythonMetaTrader5/application/trader.py index acceafa..ed0bf16 100644 --- a/src/PythonMetaTrader5/application/trader.py +++ b/src/PythonMetaTrader5/application/trader.py @@ -53,13 +53,14 @@ def open_position( fresh quote. An explicit ``price`` is sent once: re-sending the same price after a requote cannot succeed. """ + # Checked before validate_entry so a bad price never costs a symbol lookup. + fixed = None if price is None else positive_number(price, ErrorKind.INVALID_PRICE, "price") + if isinstance(fixed, Err): + return fixed entry = validate_entry(self._terminal, symbol, side, volume, comment=comment, sl=sl, tp=tp) if isinstance(entry, Err): return entry e = entry.value - fixed = None if price is None else positive_number(price, ErrorKind.INVALID_PRICE, "price") - if isinstance(fixed, Err): - return fixed def build() -> Result[OrderRequest | CancelRequest, TradeError]: if fixed is not None: @@ -90,13 +91,13 @@ def place_limit_order( A limit on the wrong side of the market is refused by the server (INVALID_PRICE) rather than converted into a market order. """ + level = positive_number(price, ErrorKind.INVALID_PRICE, "price") + if isinstance(level, Err): + return level entry = validate_entry(self._terminal, symbol, side, volume, comment=comment, sl=sl, tp=tp) if isinstance(entry, Err): return entry e = entry.value - level = positive_number(price, ErrorKind.INVALID_PRICE, "price") - if isinstance(level, Err): - return level request = e.request( e.spec.normalize_price(level.value), pending=PendingKind.LIMIT, diff --git a/src/PythonMetaTrader5/domain/inputs.py b/src/PythonMetaTrader5/domain/inputs.py index 20e3bec..6eabb7e 100644 --- a/src/PythonMetaTrader5/domain/inputs.py +++ b/src/PythonMetaTrader5/domain/inputs.py @@ -9,17 +9,19 @@ from __future__ import annotations import math +from decimal import Decimal from numbers import Integral, Real from PythonMetaTrader5.domain.errors import ErrorKind, TradeError -from PythonMetaTrader5.domain.stops import Stop +from PythonMetaTrader5.domain.stops import Stop, StopKind from PythonMetaTrader5.result import Err, Ok, Result def positive_number(value: object, kind: ErrorKind, what: str) -> Result[float, TradeError]: - # numbers.Real rather than float so numpy scalars from pandas-based bots pass; - # bool is excluded explicitly because it is a Real (True == 1). - if isinstance(value, bool) or not isinstance(value, Real): + # numbers.Real rather than float so numpy scalars from pandas-based bots pass, + # plus Decimal (not a Real) for bots that keep money as Decimal. bool is + # excluded explicitly because it is a Real (True == 1). + if isinstance(value, bool) or not isinstance(value, (Real, Decimal)): return Err(TradeError(kind, f"{what} must be a number, got {value!r}")) number = float(value) if not math.isfinite(number) or number <= 0: @@ -31,11 +33,15 @@ def stop_input(value: object, what: str) -> Result[Stop | None, TradeError]: """``None`` means no stop; a float is a price; zero is refused, never "no stop".""" if value is None: return Ok(None) + kind = value.kind if isinstance(value, Stop) else StopKind.PRICE raw = value.value if isinstance(value, Stop) else value + if kind is StopKind.POINTS and isinstance(raw, (Real, Decimal)) and not isinstance(raw, bool): + raw = abs(raw) # a points distance has no sign (see Stop._resolve) checked = positive_number(raw, ErrorKind.INVALID_STOPS, what) if isinstance(checked, Err): return checked - return Ok(value if isinstance(value, Stop) else Stop.at_price(checked.value)) + # Rebuilt from the checked float, so later arithmetic never sees a Decimal or str. + return Ok(Stop(checked.value, kind)) def ticket_filter(ticket: object) -> Result[int | None, TradeError]: diff --git a/src/PythonMetaTrader5/domain/stops.py b/src/PythonMetaTrader5/domain/stops.py index cd7bd2c..54e0def 100644 --- a/src/PythonMetaTrader5/domain/stops.py +++ b/src/PythonMetaTrader5/domain/stops.py @@ -19,15 +19,17 @@ class Stop: value: float kind: StopKind + # The factories store the value unconverted: float(True) == 1.0 would hide a + # stray bool from the input checks (domain/inputs.stop_input), which refuse + # anything that is not a positive finite number. + @classmethod def at_price(cls, price: float) -> Stop: - return cls(float(price), StopKind.PRICE) + return cls(price, StopKind.PRICE) @classmethod def points(cls, distance: float) -> Stop: - # The sign is ignored on purpose: direction comes from the trade side, so - # `-1000` and `1000` both mean "1000 points on the losing side". - return cls(abs(float(distance)), StopKind.POINTS) + return cls(distance, StopKind.POINTS) def stop_loss(self, side: Side, reference: float, spec: SymbolSpec) -> float: return self._resolve(-side.sign, reference, spec) @@ -38,4 +40,7 @@ def take_profit(self, side: Side, reference: float, spec: SymbolSpec) -> float: def _resolve(self, direction: int, reference: float, spec: SymbolSpec) -> float: if self.kind is StopKind.PRICE: return spec.normalize_price(self.value) - return spec.normalize_price(reference + direction * self.value * spec.point) + # The sign is ignored on purpose: direction comes from the trade side, so + # `-1000` and `1000` both mean "1000 points on the losing side". + distance = abs(self.value) + return spec.normalize_price(reference + direction * distance * spec.point) diff --git a/src/PythonMetaTrader5/legacy/broker.py b/src/PythonMetaTrader5/legacy/broker.py index 28fed61..3c04018 100644 --- a/src/PythonMetaTrader5/legacy/broker.py +++ b/src/PythonMetaTrader5/legacy/broker.py @@ -15,7 +15,8 @@ from PythonMetaTrader5.adapters.system_clock import SystemClock from PythonMetaTrader5.application.ports import Clock, Credentials, Terminal, parse_login from PythonMetaTrader5.application.trader import Trader -from PythonMetaTrader5.domain.errors import TradeError +from PythonMetaTrader5.domain.errors import ErrorKind, TradeError +from PythonMetaTrader5.domain.inputs import positive_number from PythonMetaTrader5.domain.market import PendingKind, TradeReceipt from PythonMetaTrader5.domain.orders import Side from PythonMetaTrader5.legacy import views @@ -236,10 +237,17 @@ def _limit( trader = self._ready() if trader is None or self._terminal is None or not no_ticket(ticket): return None - volume, stoplimit = number(volume), number(stoplimit) + volume = number(volume) if price is not None: log.error("%s: price has to be None for limit orders", self.log) return None + # Checked before the crossing test below: a level of 0 always "crosses" + # for a sell and would become a market order. + level = positive_number(number(stoplimit), ErrorKind.INVALID_PRICE, "stoplimit") + if isinstance(level, Err): + log.error("%s: %s", self.log, level.error) + return None + stoplimit = level.value tick = self._terminal.tick(symbol) if isinstance(tick, Err): log.error("%s: %s", self.log, tick.error) diff --git a/src/PythonMetaTrader5/legacy/views.py b/src/PythonMetaTrader5/legacy/views.py index d24746d..4e9294d 100644 --- a/src/PythonMetaTrader5/legacy/views.py +++ b/src/PythonMetaTrader5/legacy/views.py @@ -15,22 +15,6 @@ # MT5 POSITION_TYPE_BUY / POSITION_TYPE_SELL: 2.x callers compare `p.type == 0`. _POSITION_TYPE = {Side.BUY: 0, Side.SELL: 1} -# The keys 2.x `as_dict=True` built by hand; it never exposed the other fields. -_V2_DICT_KEYS = ( - "ticket", - "symbol", - "type", - "volume", - "price_open", - "sl", - "tp", - "price_current", - "profit", - "time", - "magic", - "comment", -) - class LegacyPosition(NamedTuple): """Field-for-field and in order the same as MetaTrader5.TradePosition.""" @@ -99,9 +83,21 @@ def as_object(p: Position) -> LegacyPosition: def as_dict(p: Position) -> dict[str, Any]: - row = as_object(p)._asdict() # 2.x `as_dict=True` used None for a missing stop, unlike the raw objects. - return {key: row[key] for key in _V2_DICT_KEYS} | {"sl": p.sl, "tp": p.tp} + return { + "ticket": p.ticket, + "symbol": p.symbol, + "type": _POSITION_TYPE[p.side], + "volume": p.volume, + "price_open": p.price_open, + "sl": p.sl, + "tp": p.tp, + "price_current": p.price_current, + "profit": p.profit, + "time": p.time, + "magic": p.magic, + "comment": p.comment, + } def as_receipt(receipt: TradeReceipt | None) -> LegacyReceipt | None: diff --git a/tests/unit/fakes.py b/tests/unit/fakes.py index 0a6acb0..06e77ba 100644 --- a/tests/unit/fakes.py +++ b/tests/unit/fakes.py @@ -89,7 +89,7 @@ class FakeTerminal: open_orders: list[PendingOrder] = field(default_factory=list) send_failure: TradeError | None = None connect_failure: TradeError | None = None - # Number of connect() calls that fail before logins start to work. + # A countdown rather than a flag, so a retry loop can be shown to recover. connect_failures: int = 0 sent: list[OrderRequest | CancelRequest] = field(default_factory=list) connected_with: list[Credentials] = field(default_factory=list) diff --git a/tests/unit/test_input_guards.py b/tests/unit/test_input_guards.py index b72d5a5..52df7fe 100644 --- a/tests/unit/test_input_guards.py +++ b/tests/unit/test_input_guards.py @@ -5,6 +5,7 @@ import math import threading from dataclasses import replace +from decimal import Decimal import pytest @@ -138,3 +139,42 @@ def blocking_positions_get(**_: object) -> None: worker.join(5) other.join(5) assert blocked, "a second adapter ran while the first was between call and last_error()" + + +@pytest.mark.parametrize("level", [0, -1.0, math.inf, math.nan, True]) +def test_legacy_limit_with_a_bad_level_sends_nothing(terminal: FakeTerminal, level: object) -> None: + # A bad level used to be compared with the quote first and "crossed" into a market order. + with pytest.warns(DeprecationWarning, match="connect"): + broker = Broker(1, "pw", "Demo", terminal=terminal, clock=FakeClock()) + assert broker.SellLimit("EURUSD", 0.1, level) is None # type: ignore[arg-type] + assert broker.BuyLimit("EURUSD", 0.1, level) is None # type: ignore[arg-type] + assert terminal.sent == [] + + +@pytest.mark.parametrize("sl_type", ["absolute", "offset"]) +def test_a_bool_stop_is_refused_however_it_is_wrapped( + trader: Trader, terminal: FakeTerminal, sl_type: str +) -> None: + for stop in (Stop.at_price(True), Stop.points(True)): # type: ignore[arg-type] + result = trader.open_position("EURUSD", "buy", 0.1, sl=stop) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_STOPS + with pytest.warns(DeprecationWarning, match="connect"): + broker = Broker(1, "pw", "Demo", terminal=terminal, clock=FakeClock()) + assert broker.OpenPosition("EURUSD", "buy", 0.1, sl=True, sl_type=sl_type) is None # type: ignore[arg-type] + assert terminal.sent == [] + + +def test_decimal_amounts_are_accepted(trader: Trader, terminal: FakeTerminal) -> None: + result = trader.open_position("EURUSD", "buy", Decimal("0.1"), price=Decimal("1.1001")) # type: ignore[arg-type] + assert isinstance(result, Ok) + request = terminal.sent[0] + assert (request.volume, request.price) == (0.1, 1.1001) # type: ignore[union-attr] + + +def test_a_bad_price_is_refused_before_any_symbol_lookup( + trader: Trader, terminal: FakeTerminal +) -> None: + trader.open_position("EURUSD", "buy", 0.1, price=math.nan) + trader.place_limit_order("EURUSD", "buy", 0.1, 0) + assert terminal.symbol_lookups == [] From 23598770e5d838387206308861689f9b008e8894 Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 03:06:57 +0100 Subject: [PATCH 18/28] refactor: Stop owns its invariants; one number rule; price checked in validate_entry Second /code-review high round, on 23f78ff, which went the wrong way: - Stop stored raw values and left the checks to stop_input. That made it an anemic value object (the project rules forbid that), and two stops with the same meaning stopped being equal: Stop.points(-1000) != Stop.points(1000). Stop.points(Decimal(...)).stop_loss() also raised TypeError. Stop now enforces positive-finite-float in __post_init__ and drops a distance's sign there, so the sign rule lives in one place instead of two. It raises ValueError, because a zero Stop cannot exist. Plain floats passed as sl/tp still come back as Err(INVALID_STOPS) from stop_input, without raising. - Decimal("sNaN") raised ValueError / InvalidOperation out of the Result boundary. domain/amounts.positive_float is the single rule, used by both Stop and positive_number, and checks Decimal NaN before float(). It is a plain function because it is pure: no port, no use case. - "Check the price before the symbol lookup" was a convention each caller had to remember. The price is now validated inside validate_entry, after side/comment/stops, so a bad side is still the first error reported. Entry carries the price on the tick grid. - as_dict is again a projection of as_object() (_V2_DICT_KEYS restored). The previous round's hand-written dict was a second mapping that could drift. Correctness wins over one allocation per row. - Tests: the bool-stop test no longer runs its Trader loop once per sl_type for nothing. The bad-price test asserts INVALID_PRICE. Error precedence is pinned. Not changed: - The legacy crossing test still compares the raw level with the quote, as 2.x did (BuyLimit: `info.ask <= float(stoplimit)`). - The legacy level check is repeated inside place_limit_order. The first check must run before the crossing test, and the second protects the 3.x API. RED: against 23f78ff's src, 20 of the new or changed cases failed (sNaN raising, Stop equality and Decimal, the Entry price field). --- README.md | 4 ++ docs/adr/0008-refuse-values-mt5-misreads.md | 21 ++++++-- src/PythonMetaTrader5/application/entries.py | 46 +++++++++++++---- src/PythonMetaTrader5/application/trader.py | 44 ++++++++-------- src/PythonMetaTrader5/domain/amounts.py | 25 +++++++++ src/PythonMetaTrader5/domain/inputs.py | 37 ++++++-------- src/PythonMetaTrader5/domain/stops.py | 22 +++++--- src/PythonMetaTrader5/legacy/arguments.py | 12 ++++- src/PythonMetaTrader5/legacy/views.py | 33 ++++++------ tests/unit/test_input_guards.py | 53 ++++++++++++++++---- 10 files changed, 204 insertions(+), 93 deletions(-) create mode 100644 src/PythonMetaTrader5/domain/amounts.py diff --git a/README.md b/README.md index 1a62dfc..bc47b1f 100644 --- a/README.md +++ b/README.md @@ -98,6 +98,10 @@ deviation=10, retry=None) -> Result[Trader, TradeError]` For limit orders the distance is measured from the limit price, and for a market order with an explicit `price` from that price. Zero, negative and non-finite stops are rejected (`INVALID_STOPS`); pass `None` for no stop. + `Stop.points()` / `Stop.at_price()` raise `ValueError` on such values, since + a zero stop would mean "no stop" to MT5. +- Amounts may be `int`, `float`, `Decimal` or numpy scalars; `bool` and strings + are refused (the deprecated `Broker` still converts numeric strings). - `price` (market orders): send at this price once instead of the live quote. - `comment`: at most 31 characters (the terminal's limit). Longer comments are rejected, not truncated. diff --git a/docs/adr/0008-refuse-values-mt5-misreads.md b/docs/adr/0008-refuse-values-mt5-misreads.md index a0d0050..3b1270d 100644 --- a/docs/adr/0008-refuse-values-mt5-misreads.md +++ b/docs/adr/0008-refuse-values-mt5-misreads.md @@ -25,9 +25,18 @@ Refuse these values at the application boundary, before any terminal call: `numbers.Real` is used rather than `float`, so numpy scalars from pandas-based bots still pass. `Decimal`, which is not a `Real`, is accepted explicitly. -- `Stop.at_price()` and `Stop.points()` store their argument unconverted. If - they called `float()`, `True` would become `1.0` before the check could see - it. +- `Stop` enforces the same rule on itself in `__post_init__`: it stores a + positive finite float, and a points distance drops its sign. It raises + `ValueError` on 0, bool, NaN, infinities and strings, because such a `Stop` + cannot exist. Plain floats passed as `sl` / `tp` are checked without raising + (`stop_input`) and come back as `INVALID_STOPS`. The number rule itself lives + once, in `domain/amounts.py`. An earlier draft stored the raw value and + checked it only in `stop_input`. We dropped it because it left `Stop` + without invariants, `Stop.points(-1000) != Stop.points(1000)`, and every + other consumer of `Stop` would have needed its own check. +- The price is checked inside `validate_entry`, before the symbol lookup and + after the side, comment and stops. A bad price never costs a terminal round + trip, and a bad side is still the first error reported. - The legacy `BuyLimit` / `SellLimit` check the level before comparing it with the quote. Otherwise a level of 0 would "cross" the market and be sent as a market order. @@ -45,5 +54,7 @@ well. - 2.x scripts that passed `sl=0` to mean "no stop" now get `None` and an error log instead of a trade. MIGRATION.md says so, and `None` is the way to ask for no stop. -- An honest zero-distance stop (`Stop.points(0)`) is refused before sending - instead of being rejected by the server with 10016. +- `Stop.points(0)` raises `ValueError` when it is built, instead of the server + rejecting it with 10016. +- Signalling-NaN Decimals are refused without raising: `float(Decimal("sNaN"))` + raises, so the NaN check runs first. diff --git a/src/PythonMetaTrader5/application/entries.py b/src/PythonMetaTrader5/application/entries.py index 083e094..0f292ec 100644 --- a/src/PythonMetaTrader5/application/entries.py +++ b/src/PythonMetaTrader5/application/entries.py @@ -29,10 +29,20 @@ class Entry: comment: str stop_loss: Stop | None take_profit: Stop | None + # The caller's price on the symbol's tick grid; None means "use the quote". + price: float | None def request( - self, reference: float, *, pending: PendingKind | None, deviation: int, magic: int + self, + quote: float | None = None, + *, + pending: PendingKind | None, + deviation: int, + magic: int, ) -> Result[OrderRequest | CancelRequest, TradeError]: + reference = self.price if self.price is not None else quote + if reference is None: + return Err(TradeError(ErrorKind.NO_PRICE, f"no price for {self.spec.name}")) spec, side = self.spec, self.side sl = self.stop_loss.stop_loss(side, reference, spec) if self.stop_loss else None tp = self.take_profit.take_profit(side, reference, spec) if self.take_profit else None @@ -68,11 +78,13 @@ def validate_entry( comment: str | None, sl: StopInput, tp: StopInput, + price: object = None, + price_required: bool = False, ) -> Result[Entry, TradeError]: - # Every check that needs no terminal runs before the symbol lookup, which - # costs a round trip and may add the symbol to Market Watch. Callers check - # their own price argument before calling this, for the same reason. - values = _caller_values(side, comment, sl, tp) + # Every check that needs no terminal, the price included, runs before the + # symbol lookup, which costs a round trip and may add the symbol to Market + # Watch. + values = _caller_values(side, comment, sl, tp, price, price_required=price_required) if isinstance(values, Err): return values amount = positive_number(volume, ErrorKind.INVALID_VOLUME, "volume") @@ -84,13 +96,20 @@ def validate_entry( lots = spec.value.validate_volume(amount.value) if isinstance(lots, Err): return lots - parsed_side, text, stop_loss, take_profit = values.value - return Ok(Entry(spec.value, parsed_side, lots.value, text, stop_loss, take_profit)) + parsed_side, text, stop_loss, take_profit, level = values.value + on_grid = None if level is None else spec.value.normalize_price(level) + return Ok(Entry(spec.value, parsed_side, lots.value, text, stop_loss, take_profit, on_grid)) def _caller_values( - side: Side | str, comment: str | None, sl: StopInput, tp: StopInput -) -> Result[tuple[Side, str, Stop | None, Stop | None], TradeError]: + side: Side | str, + comment: str | None, + sl: StopInput, + tp: StopInput, + price: object, + *, + price_required: bool, +) -> Result[tuple[Side, str, Stop | None, Stop | None, float | None], TradeError]: parsed_side = Side.parse(side) if isinstance(parsed_side, Err): return parsed_side @@ -102,4 +121,11 @@ def _caller_values( return stop_loss if isinstance(take_profit, Err): return take_profit - return Ok((parsed_side.value, text.value, stop_loss.value, take_profit.value)) + level = ( + positive_number(price, ErrorKind.INVALID_PRICE, "price") + if price is not None or price_required + else Ok(None) + ) + if isinstance(level, Err): + return level + return Ok((parsed_side.value, text.value, stop_loss.value, take_profit.value, level.value)) diff --git a/src/PythonMetaTrader5/application/trader.py b/src/PythonMetaTrader5/application/trader.py index ed0bf16..2ccd42f 100644 --- a/src/PythonMetaTrader5/application/trader.py +++ b/src/PythonMetaTrader5/application/trader.py @@ -9,8 +9,8 @@ from PythonMetaTrader5.application.entries import StopInput, validate_entry from PythonMetaTrader5.application.execution import RetryPolicy, execute from PythonMetaTrader5.application.ports import Clock, Terminal -from PythonMetaTrader5.domain.errors import ErrorKind, TradeError -from PythonMetaTrader5.domain.inputs import positive_number, symbol_filter, ticket_filter +from PythonMetaTrader5.domain.errors import TradeError +from PythonMetaTrader5.domain.inputs import symbol_filter, ticket_filter from PythonMetaTrader5.domain.market import PendingKind, PendingOrder, Position, TradeReceipt from PythonMetaTrader5.domain.orders import Side, validate_comment from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest @@ -53,24 +53,21 @@ def open_position( fresh quote. An explicit ``price`` is sent once: re-sending the same price after a requote cannot succeed. """ - # Checked before validate_entry so a bad price never costs a symbol lookup. - fixed = None if price is None else positive_number(price, ErrorKind.INVALID_PRICE, "price") - if isinstance(fixed, Err): - return fixed - entry = validate_entry(self._terminal, symbol, side, volume, comment=comment, sl=sl, tp=tp) + entry = validate_entry( + self._terminal, symbol, side, volume, comment=comment, sl=sl, tp=tp, price=price + ) if isinstance(entry, Err): return entry e = entry.value def build() -> Result[OrderRequest | CancelRequest, TradeError]: - if fixed is not None: - reference = e.spec.normalize_price(fixed.value) - else: + quote = None + if e.price is None: tick = self._terminal.tick(symbol) if isinstance(tick, Err): return tick - reference = tick.value.entry_price(e.side) - return e.request(reference, pending=None, deviation=self._deviation, magic=self._magic) + quote = tick.value.entry_price(e.side) + return e.request(quote, pending=None, deviation=self._deviation, magic=self._magic) policy = self._retry if price is None else replace(self._retry, attempts=1) return execute(self._terminal, self._clock, build, policy) @@ -91,18 +88,21 @@ def place_limit_order( A limit on the wrong side of the market is refused by the server (INVALID_PRICE) rather than converted into a market order. """ - level = positive_number(price, ErrorKind.INVALID_PRICE, "price") - if isinstance(level, Err): - return level - entry = validate_entry(self._terminal, symbol, side, volume, comment=comment, sl=sl, tp=tp) + entry = validate_entry( + self._terminal, + symbol, + side, + volume, + comment=comment, + sl=sl, + tp=tp, + price=price, + price_required=True, + ) if isinstance(entry, Err): return entry - e = entry.value - request = e.request( - e.spec.normalize_price(level.value), - pending=PendingKind.LIMIT, - deviation=self._deviation, - magic=self._magic, + request = entry.value.request( + pending=PendingKind.LIMIT, deviation=self._deviation, magic=self._magic ) if isinstance(request, Err): return request diff --git a/src/PythonMetaTrader5/domain/amounts.py b/src/PythonMetaTrader5/domain/amounts.py new file mode 100644 index 0000000..9050072 --- /dev/null +++ b/src/PythonMetaTrader5/domain/amounts.py @@ -0,0 +1,25 @@ +"""The one rule for "a positive finite number", shared by Stop and the input checks.""" + +from __future__ import annotations + +import math +from decimal import Decimal +from numbers import Real + + +def positive_float(value: object, *, unsigned: bool = False) -> float | None: + """``value`` as a positive finite float, or None when it is not one. + + numbers.Real rather than float, so numpy scalars from pandas-based bots + pass, plus Decimal (not a Real) for bots that keep money as Decimal. bool + is excluded because it is a Real (True == 1) and would trade one lot. + NaN Decimals are refused before float(): float(Decimal("sNaN")) raises. + ``unsigned`` drops the sign first (a distance), after the NaN check, because + abs(Decimal("sNaN")) raises too. + """ + if isinstance(value, bool) or not isinstance(value, (Real, Decimal)): + return None + if isinstance(value, Decimal) and value.is_nan(): + return None + number = abs(float(value)) if unsigned else float(value) + return number if math.isfinite(number) and number > 0 else None diff --git a/src/PythonMetaTrader5/domain/inputs.py b/src/PythonMetaTrader5/domain/inputs.py index 6eabb7e..a514bdb 100644 --- a/src/PythonMetaTrader5/domain/inputs.py +++ b/src/PythonMetaTrader5/domain/inputs.py @@ -8,40 +8,33 @@ from __future__ import annotations -import math -from decimal import Decimal -from numbers import Integral, Real +from numbers import Integral +from PythonMetaTrader5.domain.amounts import positive_float from PythonMetaTrader5.domain.errors import ErrorKind, TradeError -from PythonMetaTrader5.domain.stops import Stop, StopKind +from PythonMetaTrader5.domain.stops import Stop from PythonMetaTrader5.result import Err, Ok, Result def positive_number(value: object, kind: ErrorKind, what: str) -> Result[float, TradeError]: - # numbers.Real rather than float so numpy scalars from pandas-based bots pass, - # plus Decimal (not a Real) for bots that keep money as Decimal. bool is - # excluded explicitly because it is a Real (True == 1). - if isinstance(value, bool) or not isinstance(value, (Real, Decimal)): - return Err(TradeError(kind, f"{what} must be a number, got {value!r}")) - number = float(value) - if not math.isfinite(number) or number <= 0: + number = positive_float(value) + if number is None: return Err(TradeError(kind, f"{what} must be a positive finite number, got {value!r}")) return Ok(number) def stop_input(value: object, what: str) -> Result[Stop | None, TradeError]: """``None`` means no stop; a float is a price; zero is refused, never "no stop".""" - if value is None: - return Ok(None) - kind = value.kind if isinstance(value, Stop) else StopKind.PRICE - raw = value.value if isinstance(value, Stop) else value - if kind is StopKind.POINTS and isinstance(raw, (Real, Decimal)) and not isinstance(raw, bool): - raw = abs(raw) # a points distance has no sign (see Stop._resolve) - checked = positive_number(raw, ErrorKind.INVALID_STOPS, what) - if isinstance(checked, Err): - return checked - # Rebuilt from the checked float, so later arithmetic never sees a Decimal or str. - return Ok(Stop(checked.value, kind)) + if value is None or isinstance(value, Stop): + return Ok(value) # a Stop validated itself when it was built + number = positive_float(value) + if number is None: + return Err( + TradeError( + ErrorKind.INVALID_STOPS, f"{what} must be a positive finite price, got {value!r}" + ) + ) + return Ok(Stop.at_price(number)) def ticket_filter(ticket: object) -> Result[int | None, TradeError]: diff --git a/src/PythonMetaTrader5/domain/stops.py b/src/PythonMetaTrader5/domain/stops.py index 54e0def..a37110a 100644 --- a/src/PythonMetaTrader5/domain/stops.py +++ b/src/PythonMetaTrader5/domain/stops.py @@ -5,6 +5,7 @@ from dataclasses import dataclass from enum import Enum +from PythonMetaTrader5.domain.amounts import positive_float from PythonMetaTrader5.domain.orders import Side from PythonMetaTrader5.domain.symbol import SymbolSpec @@ -19,9 +20,19 @@ class Stop: value: float kind: StopKind - # The factories store the value unconverted: float(True) == 1.0 would hide a - # stray bool from the input checks (domain/inputs.stop_input), which refuse - # anything that is not a positive finite number. + def __post_init__(self) -> None: + # The invariant lives here, so every Stop is valid wherever it is built. + # A points distance drops its sign: direction comes from the trade side, + # so `-1000` and `1000` both mean "1000 points on the losing side". + number = positive_float(self.value, unsigned=self.kind is StopKind.POINTS) + if number is None: + # Raised, not returned: a Stop of 0 cannot exist (MT5 would read it as + # "no stop"), and bool/NaN/str are caller bugs. Plain floats passed as + # sl/tp are checked without raising, by domain.inputs.stop_input. + raise ValueError( + f"{self.kind.value} stop must be a positive finite number, got {self.value!r}" + ) + object.__setattr__(self, "value", number) @classmethod def at_price(cls, price: float) -> Stop: @@ -40,7 +51,4 @@ def take_profit(self, side: Side, reference: float, spec: SymbolSpec) -> float: def _resolve(self, direction: int, reference: float, spec: SymbolSpec) -> float: if self.kind is StopKind.PRICE: return spec.normalize_price(self.value) - # The sign is ignored on purpose: direction comes from the trade side, so - # `-1000` and `1000` both mean "1000 points on the losing side". - distance = abs(self.value) - return spec.normalize_price(reference + direction * distance * spec.point) + return spec.normalize_price(reference + direction * self.value * spec.point) diff --git a/src/PythonMetaTrader5/legacy/arguments.py b/src/PythonMetaTrader5/legacy/arguments.py index 65a2350..f311907 100644 --- a/src/PythonMetaTrader5/legacy/arguments.py +++ b/src/PythonMetaTrader5/legacy/arguments.py @@ -6,6 +6,7 @@ from __future__ import annotations import logging +from collections.abc import Callable from typing import Any from PythonMetaTrader5.domain.stops import Stop @@ -26,15 +27,22 @@ def number(value: Any) -> Any: def legacy_stop(value: Any, kind: str) -> Result[Stop | None, str]: if value is None: return Ok(None) + build: Callable[[Any], Stop] match (kind or "absolute").lower(): case "absolute": - return Ok(Stop.at_price(value)) + build = Stop.at_price case "offset": - return Ok(Stop.points(value)) + build = Stop.points case other: # 2.x opened the position with neither SL nor TP here. log.error("invalid stop type %r (use 'absolute' or 'offset')", other) return Err(other) + try: + return Ok(build(value)) + except ValueError as error: + # sl=0 meant "no stop" to MT5 in 2.x; refusing it beats an unprotected entry. + log.error("%s", error) + return Err(str(error)) def no_ticket(ticket: int | None) -> bool: diff --git a/src/PythonMetaTrader5/legacy/views.py b/src/PythonMetaTrader5/legacy/views.py index 4e9294d..d939231 100644 --- a/src/PythonMetaTrader5/legacy/views.py +++ b/src/PythonMetaTrader5/legacy/views.py @@ -15,6 +15,23 @@ # MT5 POSITION_TYPE_BUY / POSITION_TYPE_SELL: 2.x callers compare `p.type == 0`. _POSITION_TYPE = {Side.BUY: 0, Side.SELL: 1} +# The keys 2.x `as_dict=True` built by hand. A projection of as_object() rather +# than a second mapping, so the two 2.x shapes cannot drift apart. +_V2_DICT_KEYS = ( + "ticket", + "symbol", + "type", + "volume", + "price_open", + "sl", + "tp", + "price_current", + "profit", + "time", + "magic", + "comment", +) + class LegacyPosition(NamedTuple): """Field-for-field and in order the same as MetaTrader5.TradePosition.""" @@ -83,21 +100,9 @@ def as_object(p: Position) -> LegacyPosition: def as_dict(p: Position) -> dict[str, Any]: + row = as_object(p)._asdict() # 2.x `as_dict=True` used None for a missing stop, unlike the raw objects. - return { - "ticket": p.ticket, - "symbol": p.symbol, - "type": _POSITION_TYPE[p.side], - "volume": p.volume, - "price_open": p.price_open, - "sl": p.sl, - "tp": p.tp, - "price_current": p.price_current, - "profit": p.profit, - "time": p.time, - "magic": p.magic, - "comment": p.comment, - } + return {key: row[key] for key in _V2_DICT_KEYS} | {"sl": p.sl, "tp": p.tp} def as_receipt(receipt: TradeReceipt | None) -> LegacyReceipt | None: diff --git a/tests/unit/test_input_guards.py b/tests/unit/test_input_guards.py index 52df7fe..1af2af0 100644 --- a/tests/unit/test_input_guards.py +++ b/tests/unit/test_input_guards.py @@ -11,15 +11,17 @@ from PythonMetaTrader5 import Broker, Stop from PythonMetaTrader5.adapters.mt5_terminal import MetaTrader5Terminal +from PythonMetaTrader5.application.entries import Entry from PythonMetaTrader5.application.trader import Trader from PythonMetaTrader5.domain.errors import ErrorKind +from PythonMetaTrader5.domain.orders import Side from PythonMetaTrader5.result import Err, Ok from .fake_mt5 import FakeMT5, raw_position from .fakes import EURUSD, FakeClock, FakeTerminal, make_position -NOT_A_STOP = [0, 0.0, -1.1, math.nan, math.inf, True, Stop.points(0), Stop.at_price(0)] -NOT_A_NUMBER = [math.nan, math.inf, -math.inf, True, "0.1", None] +NOT_A_STOP = [0, 0.0, -1.1, math.nan, math.inf, True, Decimal("sNaN"), "1.1"] +NOT_A_NUMBER = [math.nan, math.inf, -math.inf, True, "0.1", Decimal("sNaN"), Decimal("NaN"), None] @pytest.mark.parametrize("stop", NOT_A_STOP) @@ -151,17 +153,29 @@ def test_legacy_limit_with_a_bad_level_sends_nothing(terminal: FakeTerminal, lev assert terminal.sent == [] -@pytest.mark.parametrize("sl_type", ["absolute", "offset"]) -def test_a_bool_stop_is_refused_however_it_is_wrapped( - trader: Trader, terminal: FakeTerminal, sl_type: str +@pytest.mark.parametrize("value", [0, -1.1, True, math.nan, math.inf, Decimal("sNaN"), "1.1"]) +@pytest.mark.parametrize("factory", [Stop.at_price, Stop.points]) +def test_a_stop_cannot_be_built_from_a_value_mt5_would_misread( + factory: object, value: object ) -> None: - for stop in (Stop.at_price(True), Stop.points(True)): # type: ignore[arg-type] - result = trader.open_position("EURUSD", "buy", 0.1, sl=stop) - assert isinstance(result, Err) - assert result.error.kind is ErrorKind.INVALID_STOPS + if factory == Stop.points and isinstance(value, float) and value < 0: + pytest.skip("a negative distance is a distance") + with pytest.raises(ValueError, match="positive finite"): + factory(value) # type: ignore[operator] + + +def test_a_stop_holds_a_float_and_a_distance_has_no_sign() -> None: + assert Stop.points(-1000) == Stop.points(1000) + assert Stop.at_price(Decimal("1.1")).value == 1.1 + assert isinstance(Stop.points(Decimal("100")).value, float) + + +@pytest.mark.parametrize("sl_type", ["absolute", "offset"]) +def test_legacy_refuses_a_bool_stop(terminal: FakeTerminal, sl_type: str) -> None: with pytest.warns(DeprecationWarning, match="connect"): broker = Broker(1, "pw", "Demo", terminal=terminal, clock=FakeClock()) assert broker.OpenPosition("EURUSD", "buy", 0.1, sl=True, sl_type=sl_type) is None # type: ignore[arg-type] + assert broker.OpenPosition("EURUSD", "buy", 0.1, sl=0, sl_type=sl_type) is None assert terminal.sent == [] @@ -175,6 +189,23 @@ def test_decimal_amounts_are_accepted(trader: Trader, terminal: FakeTerminal) -> def test_a_bad_price_is_refused_before_any_symbol_lookup( trader: Trader, terminal: FakeTerminal ) -> None: - trader.open_position("EURUSD", "buy", 0.1, price=math.nan) - trader.place_limit_order("EURUSD", "buy", 0.1, 0) + for result in ( + trader.open_position("EURUSD", "buy", 0.1, price=math.nan), + trader.place_limit_order("EURUSD", "buy", 0.1, 0), + ): + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_PRICE assert terminal.symbol_lookups == [] + + +def test_a_bad_side_is_still_reported_before_a_bad_price(trader: Trader) -> None: + result = trader.open_position("EURUSD", "hold", 0.1, price=math.nan) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_ARGUMENT + + +def test_an_entry_without_a_price_or_a_quote_sends_nothing() -> None: + entry = Entry(EURUSD, Side.BUY, 0.1, "", None, None, None) + result = entry.request(pending=None, deviation=10, magic=0) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.NO_PRICE From 591f1cb6ecfbaf5221978b5fa78167bb25dad0f0 Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 03:10:13 +0100 Subject: [PATCH 19/28] fix: refuse prices that snap to zero; Stop.parse; overflow-safe number rule Third /code-review high round, on 2359877: - An explicit price that snaps to 0.0 on the tick grid (price=1e-6 on a 5-digit symbol) was sent. A deal at price 0 fills at the market, which silently drops the caller's price. validate_entry now refuses it with INVALID_PRICE, the same guard the stops already had. - positive_float raised OverflowError on 10**400. It now returns None, so every Result path stays non-raising, including the legacy offset stop. - Stop.parse(value, kind) -> Result is the non-raising way to build a stop from a value that may be bad at runtime, e.g. an ATR that is NaN during warm-up. stop_input and legacy_stop use it, so legacy no longer catches ValueError for control flow. The constructors still raise: a Stop of 0 cannot exist, and that is the one case where the project rules allow a domain exception. Rejected alternative: making the constructors return a Result, which would turn `sl=Stop.points(1000)` into an unwrap at every call site. - Stop(1000, "points") (a str instead of a StopKind) was silently a PRICE stop. It now raises TypeError. - The retry policy is derived from e.price, the same source build() uses. - README, ADR 0008 and CHANGELOG describe the raising and the non-raising path. StopKind is exported for Stop.parse. Not changed: - Entry.request(quote=None) stays. A priced entry ignores the quote by design, and a missing price is an explicit NO_PRICE Err, covered by a test. - as_dict stays a projection of as_object. The comment now names sl/tp as the one intended difference. RED: the 4 new tests failed before the change. --- CHANGELOG.md | 2 + README.md | 12 ++++-- docs/adr/0008-refuse-values-mt5-misreads.md | 7 +++- src/PythonMetaTrader5/__init__.py | 3 +- src/PythonMetaTrader5/application/entries.py | 5 +++ src/PythonMetaTrader5/application/trader.py | 2 +- src/PythonMetaTrader5/domain/amounts.py | 5 ++- src/PythonMetaTrader5/domain/inputs.py | 15 +++---- src/PythonMetaTrader5/domain/stops.py | 39 +++++++++++++----- src/PythonMetaTrader5/legacy/arguments.py | 18 ++++---- src/PythonMetaTrader5/legacy/views.py | 3 +- tests/unit/test_input_guards.py | 43 +++++++++++++++++++- 12 files changed, 113 insertions(+), 41 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fa7e5f6..06cb4fe 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,8 @@ Complete rewrite. See [MIGRATION.md](MIGRATION.md) for every behaviour change. - Typed errors (`TradeError`, `ErrorKind`) and `BatchFailure` for close-all / cancel-all with per-ticket outcomes. - `Stop.points()` / `Stop.at_price()` for SL/TP; plain floats are prices. +- `Stop.parse(value, StopKind)` returns `Ok(stop)` / `Err(INVALID_STOPS)` for + values that may be bad at runtime; the constructors raise `ValueError`. - Magic-number support for entries and as a filter for close/cancel/queries. - Volume validation against the symbol's min/max/step. - Filling mode chosen from the symbol's allowed modes. diff --git a/README.md b/README.md index bc47b1f..cde4557 100644 --- a/README.md +++ b/README.md @@ -96,10 +96,14 @@ deviation=10, retry=None) -> Result[Trader, TradeError]` - `sl` / `tp`: a float is an **absolute price**; `Stop.points(n)` is a distance of `n` points from the entry price (`Stop.at_price(p)` is the explicit form). For limit orders the distance is measured from the limit price, and for a - market order with an explicit `price` from that price. Zero, negative and - non-finite stops are rejected (`INVALID_STOPS`); pass `None` for no stop. - `Stop.points()` / `Stop.at_price()` raise `ValueError` on such values, since - a zero stop would mean "no stop" to MT5. + market order with an explicit `price` from that price. A float stop that is + zero, negative or not finite is rejected (`INVALID_STOPS`); pass `None` for + no stop. `Stop.points()` / `Stop.at_price()` raise `ValueError` on a zero or + non-finite value (a zero stop would mean "no stop" to MT5); the sign of a + points distance is ignored. For a value that may be bad at runtime, such as + an ATR that is NaN during warm-up, use + `Stop.parse(value, StopKind.POINTS)`, which returns `Ok(stop)` / + `Err(INVALID_STOPS)`. - Amounts may be `int`, `float`, `Decimal` or numpy scalars; `bool` and strings are refused (the deprecated `Broker` still converts numeric strings). - `price` (market orders): send at this price once instead of the live quote. diff --git a/docs/adr/0008-refuse-values-mt5-misreads.md b/docs/adr/0008-refuse-values-mt5-misreads.md index 3b1270d..e5e1d91 100644 --- a/docs/adr/0008-refuse-values-mt5-misreads.md +++ b/docs/adr/0008-refuse-values-mt5-misreads.md @@ -56,5 +56,8 @@ well. to ask for no stop. - `Stop.points(0)` raises `ValueError` when it is built, instead of the server rejecting it with 10016. -- Signalling-NaN Decimals are refused without raising: `float(Decimal("sNaN"))` - raises, so the NaN check runs first. +- On the `Result` paths (`sl` / `tp` floats, volume, prices, `Stop.parse`), + signalling-NaN Decimals and numbers too large for a float are refused + without raising. `float(Decimal("sNaN"))` and `float(10**400)` both raise, + so both are handled in `positive_float`. The `Stop` constructors raise + `ValueError` on them, like on any other invalid stop. diff --git a/src/PythonMetaTrader5/__init__.py b/src/PythonMetaTrader5/__init__.py index 6923e84..61251e8 100644 --- a/src/PythonMetaTrader5/__init__.py +++ b/src/PythonMetaTrader5/__init__.py @@ -22,7 +22,7 @@ TradeReceipt, ) from PythonMetaTrader5.domain.orders import Side -from PythonMetaTrader5.domain.stops import Stop +from PythonMetaTrader5.domain.stops import Stop, StopKind from PythonMetaTrader5.legacy.broker import Broker from PythonMetaTrader5.result import Err, Ok, Result @@ -39,6 +39,7 @@ "RetryPolicy", "Side", "Stop", + "StopKind", "Tick", "TradeError", "TradeReceipt", diff --git a/src/PythonMetaTrader5/application/entries.py b/src/PythonMetaTrader5/application/entries.py index 0f292ec..528ff1f 100644 --- a/src/PythonMetaTrader5/application/entries.py +++ b/src/PythonMetaTrader5/application/entries.py @@ -98,6 +98,11 @@ def validate_entry( return lots parsed_side, text, stop_loss, take_profit, level = values.value on_grid = None if level is None else spec.value.normalize_price(level) + if on_grid is not None and on_grid <= 0: + # 1e-6 is positive but snaps to 0.0 on a 5-digit grid; a deal at price 0 + # would fill at the market and silently drop the caller's price. + message = f"price {level} snaps to {on_grid} on {spec.value.name}" + return Err(TradeError(ErrorKind.INVALID_PRICE, message)) return Ok(Entry(spec.value, parsed_side, lots.value, text, stop_loss, take_profit, on_grid)) diff --git a/src/PythonMetaTrader5/application/trader.py b/src/PythonMetaTrader5/application/trader.py index 2ccd42f..2cd5add 100644 --- a/src/PythonMetaTrader5/application/trader.py +++ b/src/PythonMetaTrader5/application/trader.py @@ -69,7 +69,7 @@ def build() -> Result[OrderRequest | CancelRequest, TradeError]: quote = tick.value.entry_price(e.side) return e.request(quote, pending=None, deviation=self._deviation, magic=self._magic) - policy = self._retry if price is None else replace(self._retry, attempts=1) + policy = self._retry if e.price is None else replace(self._retry, attempts=1) return execute(self._terminal, self._clock, build, policy) def place_limit_order( diff --git a/src/PythonMetaTrader5/domain/amounts.py b/src/PythonMetaTrader5/domain/amounts.py index 9050072..bb9b1e2 100644 --- a/src/PythonMetaTrader5/domain/amounts.py +++ b/src/PythonMetaTrader5/domain/amounts.py @@ -21,5 +21,8 @@ def positive_float(value: object, *, unsigned: bool = False) -> float | None: return None if isinstance(value, Decimal) and value.is_nan(): return None - number = abs(float(value)) if unsigned else float(value) + try: + number = abs(float(value)) if unsigned else float(value) + except (OverflowError, ValueError): + return None # 10**400 and odd Real subclasses: "not a usable number" return number if math.isfinite(number) and number > 0 else None diff --git a/src/PythonMetaTrader5/domain/inputs.py b/src/PythonMetaTrader5/domain/inputs.py index a514bdb..27533fc 100644 --- a/src/PythonMetaTrader5/domain/inputs.py +++ b/src/PythonMetaTrader5/domain/inputs.py @@ -8,11 +8,12 @@ from __future__ import annotations +from dataclasses import replace from numbers import Integral from PythonMetaTrader5.domain.amounts import positive_float from PythonMetaTrader5.domain.errors import ErrorKind, TradeError -from PythonMetaTrader5.domain.stops import Stop +from PythonMetaTrader5.domain.stops import Stop, StopKind from PythonMetaTrader5.result import Err, Ok, Result @@ -27,14 +28,10 @@ def stop_input(value: object, what: str) -> Result[Stop | None, TradeError]: """``None`` means no stop; a float is a price; zero is refused, never "no stop".""" if value is None or isinstance(value, Stop): return Ok(value) # a Stop validated itself when it was built - number = positive_float(value) - if number is None: - return Err( - TradeError( - ErrorKind.INVALID_STOPS, f"{what} must be a positive finite price, got {value!r}" - ) - ) - return Ok(Stop.at_price(number)) + parsed = Stop.parse(value, StopKind.PRICE) + if isinstance(parsed, Err): + return Err(replace(parsed.error, message=f"{what}: {parsed.error.message}")) + return Ok(parsed.value) def ticket_filter(ticket: object) -> Result[int | None, TradeError]: diff --git a/src/PythonMetaTrader5/domain/stops.py b/src/PythonMetaTrader5/domain/stops.py index a37110a..791f3e0 100644 --- a/src/PythonMetaTrader5/domain/stops.py +++ b/src/PythonMetaTrader5/domain/stops.py @@ -6,8 +6,10 @@ from enum import Enum from PythonMetaTrader5.domain.amounts import positive_float +from PythonMetaTrader5.domain.errors import ErrorKind, TradeError from PythonMetaTrader5.domain.orders import Side from PythonMetaTrader5.domain.symbol import SymbolSpec +from PythonMetaTrader5.result import Err, Ok, Result class StopKind(Enum): @@ -22,17 +24,22 @@ class Stop: def __post_init__(self) -> None: # The invariant lives here, so every Stop is valid wherever it is built. - # A points distance drops its sign: direction comes from the trade side, - # so `-1000` and `1000` both mean "1000 points on the losing side". - number = positive_float(self.value, unsigned=self.kind is StopKind.POINTS) - if number is None: - # Raised, not returned: a Stop of 0 cannot exist (MT5 would read it as - # "no stop"), and bool/NaN/str are caller bugs. Plain floats passed as - # sl/tp are checked without raising, by domain.inputs.stop_input. - raise ValueError( - f"{self.kind.value} stop must be a positive finite number, got {self.value!r}" - ) - object.__setattr__(self, "value", number) + # Raised, not returned: a Stop of 0 cannot exist (MT5 would read it as "no + # stop"). Code holding a value that may be bad (an ATR that is NaN during + # warm-up) uses Stop.parse, which returns a Result instead. + if not isinstance(self.kind, StopKind): + raise TypeError(f"kind must be a StopKind, got {self.kind!r}") + parsed = _checked(self.value, self.kind) + if isinstance(parsed, Err): + raise ValueError(parsed.error.message) + object.__setattr__(self, "value", parsed.value) + + @classmethod + def parse(cls, value: object, kind: StopKind) -> Result[Stop, TradeError]: + checked = _checked(value, kind) + if isinstance(checked, Err): + return checked + return Ok(cls(checked.value, kind)) @classmethod def at_price(cls, price: float) -> Stop: @@ -52,3 +59,13 @@ def _resolve(self, direction: int, reference: float, spec: SymbolSpec) -> float: if self.kind is StopKind.PRICE: return spec.normalize_price(self.value) return spec.normalize_price(reference + direction * self.value * spec.point) + + +def _checked(value: object, kind: StopKind) -> Result[float, TradeError]: + # A points distance drops its sign: direction comes from the trade side, so + # `-1000` and `1000` both mean "1000 points on the losing side". + number = positive_float(value, unsigned=kind is StopKind.POINTS) + if number is None: + message = f"{kind.value} stop must be a positive finite number, got {value!r}" + return Err(TradeError(ErrorKind.INVALID_STOPS, message)) + return Ok(number) diff --git a/src/PythonMetaTrader5/legacy/arguments.py b/src/PythonMetaTrader5/legacy/arguments.py index f311907..167fc5c 100644 --- a/src/PythonMetaTrader5/legacy/arguments.py +++ b/src/PythonMetaTrader5/legacy/arguments.py @@ -6,10 +6,9 @@ from __future__ import annotations import logging -from collections.abc import Callable from typing import Any -from PythonMetaTrader5.domain.stops import Stop +from PythonMetaTrader5.domain.stops import Stop, StopKind from PythonMetaTrader5.result import Err, Ok, Result log = logging.getLogger("PythonMetaTrader5.legacy") @@ -27,22 +26,21 @@ def number(value: Any) -> Any: def legacy_stop(value: Any, kind: str) -> Result[Stop | None, str]: if value is None: return Ok(None) - build: Callable[[Any], Stop] match (kind or "absolute").lower(): case "absolute": - build = Stop.at_price + stop_kind = StopKind.PRICE case "offset": - build = Stop.points + stop_kind = StopKind.POINTS case other: # 2.x opened the position with neither SL nor TP here. log.error("invalid stop type %r (use 'absolute' or 'offset')", other) return Err(other) - try: - return Ok(build(value)) - except ValueError as error: + parsed = Stop.parse(value, stop_kind) + if isinstance(parsed, Err): # sl=0 meant "no stop" to MT5 in 2.x; refusing it beats an unprotected entry. - log.error("%s", error) - return Err(str(error)) + log.error("%s", parsed.error) + return Err(parsed.error.message) + return Ok(parsed.value) def no_ticket(ticket: int | None) -> bool: diff --git a/src/PythonMetaTrader5/legacy/views.py b/src/PythonMetaTrader5/legacy/views.py index d939231..ead66f8 100644 --- a/src/PythonMetaTrader5/legacy/views.py +++ b/src/PythonMetaTrader5/legacy/views.py @@ -16,7 +16,8 @@ _POSITION_TYPE = {Side.BUY: 0, Side.SELL: 1} # The keys 2.x `as_dict=True` built by hand. A projection of as_object() rather -# than a second mapping, so the two 2.x shapes cannot drift apart. +# than a second mapping, so the shared fields cannot drift apart; only sl/tp +# differ on purpose (None instead of 0.0, as in 2.x). _V2_DICT_KEYS = ( "ticket", "symbol", diff --git a/tests/unit/test_input_guards.py b/tests/unit/test_input_guards.py index 1af2af0..6a73c1e 100644 --- a/tests/unit/test_input_guards.py +++ b/tests/unit/test_input_guards.py @@ -9,7 +9,7 @@ import pytest -from PythonMetaTrader5 import Broker, Stop +from PythonMetaTrader5 import Broker, Stop, StopKind from PythonMetaTrader5.adapters.mt5_terminal import MetaTrader5Terminal from PythonMetaTrader5.application.entries import Entry from PythonMetaTrader5.application.trader import Trader @@ -209,3 +209,44 @@ def test_an_entry_without_a_price_or_a_quote_sends_nothing() -> None: result = entry.request(pending=None, deviation=10, magic=0) assert isinstance(result, Err) assert result.error.kind is ErrorKind.NO_PRICE + + +def test_a_price_that_snaps_to_zero_is_refused_before_sending( + trader: Trader, terminal: FakeTerminal +) -> None: + for result in ( + trader.open_position("EURUSD", "buy", 0.1, price=1e-6), + trader.place_limit_order("EURUSD", "buy", 0.1, 0.000004), + ): + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_PRICE + assert terminal.sent == [] + + +def test_numbers_too_large_for_a_float_are_refused_not_raised( + trader: Trader, terminal: FakeTerminal +) -> None: + huge = 10**400 + for result, kind in ( + (trader.open_position("EURUSD", "buy", huge), ErrorKind.INVALID_VOLUME), + (trader.open_position("EURUSD", "buy", 0.1, sl=huge), ErrorKind.INVALID_STOPS), + ): + assert isinstance(result, Err) + assert result.error.kind is kind + with pytest.warns(DeprecationWarning, match="connect"): + broker = Broker(1, "pw", "Demo", terminal=terminal, clock=FakeClock()) + assert broker.OpenPosition("EURUSD", "buy", 0.1, sl=huge, sl_type="offset") is None + assert terminal.sent == [] + + +def test_stop_parse_is_the_non_raising_way_to_build_a_stop() -> None: + assert Stop.parse(-1000, StopKind.POINTS) == Ok(Stop.points(1000)) + for value in (math.nan, 0, True): + parsed = Stop.parse(value, StopKind.POINTS) + assert isinstance(parsed, Err) + assert parsed.error.kind is ErrorKind.INVALID_STOPS + + +def test_a_stop_kind_must_be_a_stop_kind() -> None: + with pytest.raises(TypeError, match="StopKind"): + Stop(1000, "points") # type: ignore[arg-type] From 048ab75a601966ebfe3072481fcdc033855ce075 Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 03:13:39 +0100 Subject: [PATCH 20/28] fix: one tick-grid helper returning Result for every sent level Fourth /code-review high round, on 591f1cb: - price=1e305, a limit at 1e305 and sl/tp=1e305 raised OverflowError. They passed the number rule (finite), then 1e305 / 1e-5 overflowed to inf in normalize_price and round(inf) raised. SymbolSpec.price_on_grid is now the single place every sent level (entry price, sl, tp) goes on the grid. It returns Err on overflow, on a level that snaps to 0 or below, and on a symbol with neither tick size nor point. This replaces the two ad-hoc "normalize, then check <= 0" copies, which had already diverged: neither one guarded the overflow. Stop.stop_loss/take_profit return a Result accordingly. - Stop.parse(0, "points") raised AttributeError and Stop.parse(5, "points") raised TypeError. The kind check now runs first, inside the shared _checked, so a wrong kind is always a TypeError. - positive_float catches only OverflowError, the one named case. Catching ValueError would have hidden bugs in a caller's own number type, with a misleading message and no traceback. - README, ADR 0008 and CHANGELOG now say exactly what the Stop constructors raise on, and how large finite floats are handled. Not changed: Stop.parse validates once in _checked and again in __post_init__. Both calls go through the same function, so they cannot diverge, and the alternative of catching ValueError is the exception-driven control flow the previous round removed. RED: the overflow and parse-kind tests failed before the change. The test_stops expectations moved to Ok(...) with the new return type. --- CHANGELOG.md | 3 +- README.md | 9 +++-- docs/adr/0008-refuse-values-mt5-misreads.md | 11 +++--- src/PythonMetaTrader5/application/entries.py | 35 ++++++++++---------- src/PythonMetaTrader5/domain/amounts.py | 8 +++-- src/PythonMetaTrader5/domain/stops.py | 30 +++++++++++------ src/PythonMetaTrader5/domain/symbol.py | 20 +++++++++++ tests/unit/test_input_guards.py | 29 ++++++++++++++++ tests/unit/test_stops.py | 11 +++--- 9 files changed, 114 insertions(+), 42 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 06cb4fe..ba2d163 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,7 +14,8 @@ Complete rewrite. See [MIGRATION.md](MIGRATION.md) for every behaviour change. cancel-all with per-ticket outcomes. - `Stop.points()` / `Stop.at_price()` for SL/TP; plain floats are prices. - `Stop.parse(value, StopKind)` returns `Ok(stop)` / `Err(INVALID_STOPS)` for - values that may be bad at runtime; the constructors raise `ValueError`. + values that may be bad at runtime; the constructors raise `ValueError`, and + a `kind` that is not a `StopKind` raises `TypeError`. - Magic-number support for entries and as a filter for close/cancel/queries. - Volume validation against the symbol's min/max/step. - Filling mode chosen from the symbol's allowed modes. diff --git a/README.md b/README.md index cde4557..66b8ca9 100644 --- a/README.md +++ b/README.md @@ -98,9 +98,12 @@ deviation=10, retry=None) -> Result[Trader, TradeError]` For limit orders the distance is measured from the limit price, and for a market order with an explicit `price` from that price. A float stop that is zero, negative or not finite is rejected (`INVALID_STOPS`); pass `None` for - no stop. `Stop.points()` / `Stop.at_price()` raise `ValueError` on a zero or - non-finite value (a zero stop would mean "no stop" to MT5); the sign of a - points distance is ignored. For a value that may be bad at runtime, such as + no stop. `Stop.points()` / `Stop.at_price()` raise `ValueError` unless the + value is a positive finite number (bool and str included; a zero stop would + mean "no stop" to MT5); the sign of a points distance is ignored. A `kind` + that is not a `StopKind` raises `TypeError`. A stop that resolves outside + the tick grid's range, or to zero or below, is `INVALID_STOPS` when the + order is built. For a value that may be bad at runtime, such as an ATR that is NaN during warm-up, use `Stop.parse(value, StopKind.POINTS)`, which returns `Ok(stop)` / `Err(INVALID_STOPS)`. diff --git a/docs/adr/0008-refuse-values-mt5-misreads.md b/docs/adr/0008-refuse-values-mt5-misreads.md index e5e1d91..a4f2e28 100644 --- a/docs/adr/0008-refuse-values-mt5-misreads.md +++ b/docs/adr/0008-refuse-values-mt5-misreads.md @@ -57,7 +57,10 @@ well. - `Stop.points(0)` raises `ValueError` when it is built, instead of the server rejecting it with 10016. - On the `Result` paths (`sl` / `tp` floats, volume, prices, `Stop.parse`), - signalling-NaN Decimals and numbers too large for a float are refused - without raising. `float(Decimal("sNaN"))` and `float(10**400)` both raise, - so both are handled in `positive_float`. The `Stop` constructors raise - `ValueError` on them, like on any other invalid stop. + signalling-NaN Decimals and ints too large for a float are refused without + raising. `float(Decimal("sNaN"))` and `float(10**400)` both raise, so + `positive_float` handles both. Large but finite floats (`1e305`) pass that + rule, but they overflow on the tick grid (`1e305 / 1e-5` is `inf`). + `SymbolSpec.price_on_grid` is the one place every sent level is put on the + grid, and it refuses those as well as levels that snap to 0. The `Stop` + constructors raise `ValueError` on any invalid value. diff --git a/src/PythonMetaTrader5/application/entries.py b/src/PythonMetaTrader5/application/entries.py index 528ff1f..960290f 100644 --- a/src/PythonMetaTrader5/application/entries.py +++ b/src/PythonMetaTrader5/application/entries.py @@ -44,14 +44,12 @@ def request( if reference is None: return Err(TradeError(ErrorKind.NO_PRICE, f"no price for {self.spec.name}")) spec, side = self.spec, self.side - sl = self.stop_loss.stop_loss(side, reference, spec) if self.stop_loss else None - tp = self.take_profit.take_profit(side, reference, spec) if self.take_profit else None - for name, level in (("sl", sl), ("tp", tp)): - # A tiny price snaps to 0.0 and a long points distance goes below - # zero; MT5 would read the first as "no stop". - if level is not None and level <= 0: - message = f"{name} resolves to {level} on {spec.name}" - return Err(TradeError(ErrorKind.INVALID_STOPS, message)) + sl = self.stop_loss.stop_loss(side, reference, spec) if self.stop_loss else Ok(None) + if isinstance(sl, Err): + return sl + tp = self.take_profit.take_profit(side, reference, spec) if self.take_profit else Ok(None) + if isinstance(tp, Err): + return tp return Ok( OrderRequest( symbol=spec.name, @@ -62,8 +60,8 @@ def request( deviation=deviation, magic=magic, comment=self.comment, - sl=sl, - tp=tp, + sl=sl.value, + tp=tp.value, pending=pending, ) ) @@ -97,13 +95,16 @@ def validate_entry( if isinstance(lots, Err): return lots parsed_side, text, stop_loss, take_profit, level = values.value - on_grid = None if level is None else spec.value.normalize_price(level) - if on_grid is not None and on_grid <= 0: - # 1e-6 is positive but snaps to 0.0 on a 5-digit grid; a deal at price 0 - # would fill at the market and silently drop the caller's price. - message = f"price {level} snaps to {on_grid} on {spec.value.name}" - return Err(TradeError(ErrorKind.INVALID_PRICE, message)) - return Ok(Entry(spec.value, parsed_side, lots.value, text, stop_loss, take_profit, on_grid)) + on_grid = ( + Ok(None) + if level is None + else spec.value.price_on_grid(level, ErrorKind.INVALID_PRICE, "price") + ) + if isinstance(on_grid, Err): + return on_grid + return Ok( + Entry(spec.value, parsed_side, lots.value, text, stop_loss, take_profit, on_grid.value) + ) def _caller_values( diff --git a/src/PythonMetaTrader5/domain/amounts.py b/src/PythonMetaTrader5/domain/amounts.py index bb9b1e2..14d3416 100644 --- a/src/PythonMetaTrader5/domain/amounts.py +++ b/src/PythonMetaTrader5/domain/amounts.py @@ -23,6 +23,10 @@ def positive_float(value: object, *, unsigned: bool = False) -> float | None: return None try: number = abs(float(value)) if unsigned else float(value) - except (OverflowError, ValueError): - return None # 10**400 and odd Real subclasses: "not a usable number" + except OverflowError: + # None rather than raising: an int beyond float range (10**400) is bad + # input like NaN, and raising would break the Result boundary. Other + # float() errors are not caught: they are bugs in the caller's type and + # must keep their traceback. + return None return number if math.isfinite(number) and number > 0 else None diff --git a/src/PythonMetaTrader5/domain/stops.py b/src/PythonMetaTrader5/domain/stops.py index 791f3e0..e0ea389 100644 --- a/src/PythonMetaTrader5/domain/stops.py +++ b/src/PythonMetaTrader5/domain/stops.py @@ -27,8 +27,6 @@ def __post_init__(self) -> None: # Raised, not returned: a Stop of 0 cannot exist (MT5 would read it as "no # stop"). Code holding a value that may be bad (an ATR that is NaN during # warm-up) uses Stop.parse, which returns a Result instead. - if not isinstance(self.kind, StopKind): - raise TypeError(f"kind must be a StopKind, got {self.kind!r}") parsed = _checked(self.value, self.kind) if isinstance(parsed, Err): raise ValueError(parsed.error.message) @@ -49,19 +47,31 @@ def at_price(cls, price: float) -> Stop: def points(cls, distance: float) -> Stop: return cls(distance, StopKind.POINTS) - def stop_loss(self, side: Side, reference: float, spec: SymbolSpec) -> float: - return self._resolve(-side.sign, reference, spec) + def stop_loss( + self, side: Side, reference: float, spec: SymbolSpec + ) -> Result[float, TradeError]: + return self._resolve(-side.sign, reference, spec, "sl") - def take_profit(self, side: Side, reference: float, spec: SymbolSpec) -> float: - return self._resolve(side.sign, reference, spec) + def take_profit( + self, side: Side, reference: float, spec: SymbolSpec + ) -> Result[float, TradeError]: + return self._resolve(side.sign, reference, spec, "tp") - def _resolve(self, direction: int, reference: float, spec: SymbolSpec) -> float: - if self.kind is StopKind.PRICE: - return spec.normalize_price(self.value) - return spec.normalize_price(reference + direction * self.value * spec.point) + def _resolve( + self, direction: int, reference: float, spec: SymbolSpec, what: str + ) -> Result[float, TradeError]: + # A long points distance can go below zero; price_on_grid refuses that. + level = self.value + if self.kind is StopKind.POINTS: + level = reference + direction * self.value * spec.point + return spec.price_on_grid(level, ErrorKind.INVALID_STOPS, what) def _checked(value: object, kind: StopKind) -> Result[float, TradeError]: + # A wrong kind is a programming error, raised for every value alike (also by + # Stop.parse), rather than read as a price. + if not isinstance(kind, StopKind): + raise TypeError(f"kind must be a StopKind, got {kind!r}") # A points distance drops its sign: direction comes from the trade side, so # `-1000` and `1000` both mean "1000 points on the losing side". number = positive_float(value, unsigned=kind is StopKind.POINTS) diff --git a/src/PythonMetaTrader5/domain/symbol.py b/src/PythonMetaTrader5/domain/symbol.py index 10e7b9c..1089683 100644 --- a/src/PythonMetaTrader5/domain/symbol.py +++ b/src/PythonMetaTrader5/domain/symbol.py @@ -2,6 +2,7 @@ from __future__ import annotations +import math from dataclasses import dataclass from enum import Enum @@ -48,6 +49,25 @@ def normalize_price(self, price: float) -> float: step = self.tick_size if self.tick_size > 0 else self.point return round(round(price / step) * step, self.digits) + def price_on_grid(self, price: float, kind: ErrorKind, what: str) -> Result[float, TradeError]: + """``price`` on the tick grid, refused if it is not a usable positive level. + + The one place every sent level (entry price, sl, tp) is put on the grid, + so the two ways a positive finite input still goes wrong are checked + once: 1e305 / 1e-5 overflows to inf (round(inf) raises), and 1e-6 + snaps to 0.0, which MT5 reads as "no stop" or "fill at the market". + """ + step = self.tick_size if self.tick_size > 0 else self.point + if step <= 0: + # Broken symbol data, refused like a zero volume_step. + return Err(TradeError(kind, f"{self.name} reports no tick size or point")) + if not math.isfinite(price / step): + return Err(TradeError(kind, f"{what} {price} is out of range for {self.name}")) + level = self.normalize_price(price) + if level <= 0: + return Err(TradeError(kind, f"{what} {price} snaps to {level} on {self.name}")) + return Ok(level) + def validate_volume(self, volume: float) -> Result[float, TradeError]: if self.volume_step <= 0: # Broken symbol data: refusing is the only safe answer, guessing a diff --git a/tests/unit/test_input_guards.py b/tests/unit/test_input_guards.py index 6a73c1e..d6515a3 100644 --- a/tests/unit/test_input_guards.py +++ b/tests/unit/test_input_guards.py @@ -250,3 +250,32 @@ def test_stop_parse_is_the_non_raising_way_to_build_a_stop() -> None: def test_a_stop_kind_must_be_a_stop_kind() -> None: with pytest.raises(TypeError, match="StopKind"): Stop(1000, "points") # type: ignore[arg-type] + + +def test_a_finite_price_too_large_for_the_tick_grid_is_refused_not_raised( + trader: Trader, terminal: FakeTerminal +) -> None: + for result, kind in ( + (trader.open_position("EURUSD", "buy", 0.1, price=1e305), ErrorKind.INVALID_PRICE), + (trader.place_limit_order("EURUSD", "buy", 0.1, 1e305), ErrorKind.INVALID_PRICE), + (trader.open_position("EURUSD", "buy", 0.1, sl=1e305), ErrorKind.INVALID_STOPS), + (trader.open_position("EURUSD", "buy", 0.1, tp=1e305), ErrorKind.INVALID_STOPS), + ): + assert isinstance(result, Err) + assert result.error.kind is kind + assert terminal.sent == [] + + +def test_stop_parse_reports_a_wrong_kind_as_a_type_error_for_any_value() -> None: + for value in (0, 5): + with pytest.raises(TypeError, match="StopKind"): + Stop.parse(value, "points") # type: ignore[arg-type] + + +def test_a_symbol_without_tick_size_or_point_cannot_price_anything( + trader: Trader, terminal: FakeTerminal +) -> None: + terminal.specs["EURUSD"] = replace(EURUSD, tick_size=0.0, point=0.0) + result = trader.place_limit_order("EURUSD", "buy", 0.1, 1.05) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_PRICE diff --git a/tests/unit/test_stops.py b/tests/unit/test_stops.py index 6f51b83..cb02f82 100644 --- a/tests/unit/test_stops.py +++ b/tests/unit/test_stops.py @@ -3,6 +3,7 @@ from PythonMetaTrader5.domain.orders import Side from PythonMetaTrader5.domain.stops import Stop from PythonMetaTrader5.domain.symbol import SymbolSpec +from PythonMetaTrader5.result import Ok SPEC = SymbolSpec( name="EURUSD", @@ -18,8 +19,8 @@ def test_absolute_stop_is_only_normalized() -> None: - assert Stop.at_price(1.123456).stop_loss(Side.BUY, 1.2, SPEC) == 1.12346 - assert Stop.at_price(1.123456).take_profit(Side.SELL, 1.2, SPEC) == 1.12346 + assert Stop.at_price(1.123456).stop_loss(Side.BUY, 1.2, SPEC) == Ok(1.12346) + assert Stop.at_price(1.123456).take_profit(Side.SELL, 1.2, SPEC) == Ok(1.12346) @pytest.mark.parametrize( @@ -30,9 +31,9 @@ def test_point_offsets_follow_trade_direction( side: Side, stop_loss: float, take_profit: float ) -> None: reference = 1.1 - assert Stop.points(1000).stop_loss(side, reference, SPEC) == stop_loss - assert Stop.points(1500).take_profit(side, reference, SPEC) == take_profit + assert Stop.points(1000).stop_loss(side, reference, SPEC) == Ok(stop_loss) + assert Stop.points(1500).take_profit(side, reference, SPEC) == Ok(take_profit) def test_negative_offset_is_treated_as_distance() -> None: - assert Stop.points(-1000).stop_loss(Side.BUY, 1.1, SPEC) == 1.09 + assert Stop.points(-1000).stop_loss(Side.BUY, 1.1, SPEC) == Ok(1.09) From a0f2aba4b4bbe2fa8e8c96641a35f774929209c2 Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 03:17:32 +0100 Subject: [PATCH 21/28] fix: SymbolSpec refuses broken terminal data; absolute stops checked before quotes Fifth /code-review high round, on 048ab75: - With point=inf (and tick_size=0), price_on_grid returned Ok(nan) and an order priced NaN was sent. With point=0, Stop.points(1000) resolved to the entry price. SymbolSpec now has an invariant: point, volume_step and volume_min must be positive and finite, tick_size must be 0 or positive and finite, volume_max must be >= volume_min, and digits >= 0. __post_init__ raises, because such a spec cannot exist, and the adapter goes through SymbolSpec.check, which turns broken data into Err(TERMINAL_ERROR). This removes the scattered step guards in validate_volume and price_on_grid. They are unreachable now, and they had already missed the inf case. The step choice lives once, in _step. - Absolute sl/tp are checked on the grid in validate_entry. A stop that can never be valid no longer waits through the NO_PRICE retries of a symbol without quotes before it is reported. - positive_float catches ArithmeticError (overflow, and numpy FloatingPointError under seterr), which covers numbers out of range. It still lets ValueError/TypeError through: those are bugs in the caller's own type. - The price_on_grid docstring and ADR 0008 no longer claim that quote prices pass through it. A stops.py comment now states the decision. Not changed: - Stop.parse raises TypeError on a kind that is not a StopKind. A config string has to go through StopKind(...) first, which raises ValueError by itself. - Stop.stop_loss/take_profit returning a Result needs no migration note: Stop is new in 3.0, which is unreleased. RED: all 19 cases in the new test_symbol_data.py failed before the change. The two tests that built impossible specs (volume_step=0, point=0) were replaced by adapter-level tests, because such specs can no longer be built. --- CHANGELOG.md | 3 + docs/adr/0008-refuse-values-mt5-misreads.md | 12 +++- .../adapters/mt5_terminal.py | 24 +++---- src/PythonMetaTrader5/application/entries.py | 25 +++++-- src/PythonMetaTrader5/domain/amounts.py | 11 +-- src/PythonMetaTrader5/domain/stops.py | 3 +- src/PythonMetaTrader5/domain/symbol.py | 63 ++++++++++++----- tests/unit/test_input_guards.py | 19 ------ tests/unit/test_symbol_data.py | 68 +++++++++++++++++++ 9 files changed, 167 insertions(+), 61 deletions(-) create mode 100644 tests/unit/test_symbol_data.py diff --git a/CHANGELOG.md b/CHANGELOG.md index ba2d163..833464e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -60,6 +60,9 @@ Complete rewrite. See [MIGRATION.md](MIGRATION.md) for every behaviour change. - `sl=0` / `tp=0`, stops that resolve to zero or below, tickets that are not positive integers, `volume=True` and non-finite numbers are rejected before sending. +- Symbol data that cannot price an order (point 0 or infinite, volume step + 0, ...) is refused as `TERMINAL_ERROR` instead of producing NaN prices or + stops on the entry price. - `positions(symbol, ticket=...)` applies both filters (MT5 drops the symbol once a ticket is given). - Pending orders on exchange-execution symbols use RETURN filling. diff --git a/docs/adr/0008-refuse-values-mt5-misreads.md b/docs/adr/0008-refuse-values-mt5-misreads.md index a4f2e28..fda0122 100644 --- a/docs/adr/0008-refuse-values-mt5-misreads.md +++ b/docs/adr/0008-refuse-values-mt5-misreads.md @@ -61,6 +61,14 @@ well. raising. `float(Decimal("sNaN"))` and `float(10**400)` both raise, so `positive_float` handles both. Large but finite floats (`1e305`) pass that rule, but they overflow on the tick grid (`1e305 / 1e-5` is `inf`). - `SymbolSpec.price_on_grid` is the one place every sent level is put on the - grid, and it refuses those as well as levels that snap to 0. The `Stop` + `SymbolSpec.price_on_grid` is the one place every caller-supplied level is + put on the grid, and it refuses those as well as levels that snap to 0. + Quote prices come from the terminal already on the grid. The `Stop` constructors raise `ValueError` on any invalid value. +- Broken symbol data from the terminal is the same problem on the other + side. A point of 0 put a points stop on the entry price, and a point of + inf priced orders at NaN. `SymbolSpec` therefore has an invariant: point, + volume step and volume min must be positive and finite, the tick size must + be 0 or positive and finite, and volume max must not be below volume min. + The adapter turns a violation into `Err(TERMINAL_ERROR)` through + `SymbolSpec.check`. diff --git a/src/PythonMetaTrader5/adapters/mt5_terminal.py b/src/PythonMetaTrader5/adapters/mt5_terminal.py index dc8a310..cd96eb4 100644 --- a/src/PythonMetaTrader5/adapters/mt5_terminal.py +++ b/src/PythonMetaTrader5/adapters/mt5_terminal.py @@ -137,18 +137,18 @@ def symbol(self, name: str) -> Result[SymbolSpec, TradeError]: f"{name!r} cannot be added to Market Watch: {self._last_error()}", ) ) - return Ok( - SymbolSpec( - name=info.name, - digits=int(info.digits), - point=float(info.point), - tick_size=float(info.trade_tick_size), - volume_min=float(info.volume_min), - volume_max=float(info.volume_max), - volume_step=float(info.volume_step), - filling_flags=int(info.filling_mode), - exchange_execution=int(info.trade_exemode) == self._exchange_execution, - ) + return SymbolSpec.check( + { + "name": info.name, + "digits": int(info.digits), + "point": float(info.point), + "tick_size": float(info.trade_tick_size), + "volume_min": float(info.volume_min), + "volume_max": float(info.volume_max), + "volume_step": float(info.volume_step), + "filling_flags": int(info.filling_mode), + "exchange_execution": int(info.trade_exemode) == self._exchange_execution, + } ) @_serialized diff --git a/src/PythonMetaTrader5/application/entries.py b/src/PythonMetaTrader5/application/entries.py index 960290f..49aaf73 100644 --- a/src/PythonMetaTrader5/application/entries.py +++ b/src/PythonMetaTrader5/application/entries.py @@ -14,7 +14,7 @@ from PythonMetaTrader5.domain.market import PendingKind from PythonMetaTrader5.domain.orders import Side, validate_comment from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest -from PythonMetaTrader5.domain.stops import Stop +from PythonMetaTrader5.domain.stops import Stop, StopKind from PythonMetaTrader5.domain.symbol import SymbolSpec from PythonMetaTrader5.result import Err, Ok, Result @@ -95,11 +95,7 @@ def validate_entry( if isinstance(lots, Err): return lots parsed_side, text, stop_loss, take_profit, level = values.value - on_grid = ( - Ok(None) - if level is None - else spec.value.price_on_grid(level, ErrorKind.INVALID_PRICE, "price") - ) + on_grid = _quote_free_levels(spec.value, level, stop_loss, take_profit) if isinstance(on_grid, Err): return on_grid return Ok( @@ -107,6 +103,23 @@ def validate_entry( ) +def _quote_free_levels( + spec: SymbolSpec, price: float | None, sl: Stop | None, tp: Stop | None +) -> Result[float | None, TradeError]: + # Absolute stops do not depend on the quote, so they are checked here, before + # the first tick request: otherwise a stop that can never be valid would sit + # through the NO_PRICE retries of a symbol without quotes first. + for name, stop in (("sl", sl), ("tp", tp)): + if stop is not None and stop.kind is StopKind.PRICE: + checked = spec.price_on_grid(stop.value, ErrorKind.INVALID_STOPS, name) + if isinstance(checked, Err): + return checked + if price is None: + return Ok(None) + level = spec.price_on_grid(price, ErrorKind.INVALID_PRICE, "price") + return level if isinstance(level, Err) else Ok(level.value) + + def _caller_values( side: Side | str, comment: str | None, diff --git a/src/PythonMetaTrader5/domain/amounts.py b/src/PythonMetaTrader5/domain/amounts.py index 14d3416..84c53cf 100644 --- a/src/PythonMetaTrader5/domain/amounts.py +++ b/src/PythonMetaTrader5/domain/amounts.py @@ -23,10 +23,11 @@ def positive_float(value: object, *, unsigned: bool = False) -> float | None: return None try: number = abs(float(value)) if unsigned else float(value) - except OverflowError: - # None rather than raising: an int beyond float range (10**400) is bad - # input like NaN, and raising would break the Result boundary. Other - # float() errors are not caught: they are bugs in the caller's type and - # must keep their traceback. + except ArithmeticError: + # None rather than raising: a number outside float range (10**400, or a + # numpy longdouble under np.seterr(over="raise")) is bad input like NaN, + # and raising would break the Result boundary. ValueError/TypeError are + # not caught: they are bugs in the caller's own type and must keep + # their traceback. return None return number if math.isfinite(number) and number > 0 else None diff --git a/src/PythonMetaTrader5/domain/stops.py b/src/PythonMetaTrader5/domain/stops.py index e0ea389..d5161c0 100644 --- a/src/PythonMetaTrader5/domain/stops.py +++ b/src/PythonMetaTrader5/domain/stops.py @@ -60,7 +60,8 @@ def take_profit( def _resolve( self, direction: int, reference: float, spec: SymbolSpec, what: str ) -> Result[float, TradeError]: - # A long points distance can go below zero; price_on_grid refuses that. + # Resolved without a sign check here: price_on_grid is the single place a + # level below zero (a long points distance) or off the grid is refused. level = self.value if self.kind is StopKind.POINTS: level = reference + direction * self.value * spec.point diff --git a/src/PythonMetaTrader5/domain/symbol.py b/src/PythonMetaTrader5/domain/symbol.py index 1089683..6251561 100644 --- a/src/PythonMetaTrader5/domain/symbol.py +++ b/src/PythonMetaTrader5/domain/symbol.py @@ -43,25 +43,42 @@ class SymbolSpec: # market execution and send limits that cancel instead of resting. exchange_execution: bool - def normalize_price(self, price: float) -> float: + def __post_init__(self) -> None: + # The invariant lives here so pricing code never meets a zero, NaN or + # infinite step: point 0 put a points stop on the entry price, point inf + # priced orders at NaN. Raised, not returned: such a spec cannot exist; + # the adapter turns terminal data into a Result through SymbolSpec.check. + problem = _problem(self) + if problem is not None: + raise ValueError(f"{self.name}: {problem}") + + @staticmethod + def check(spec_fields: dict[str, object]) -> Result[SymbolSpec, TradeError]: + try: + return Ok(SymbolSpec(**spec_fields)) # type: ignore[arg-type] + except ValueError as error: + return Err(TradeError(ErrorKind.TERMINAL_ERROR, f"broken symbol data: {error}")) + + @property + def _step(self) -> float: # A price must sit on the tick grid, not merely have `digits` decimals: # index CFDs often have tick 0.25 with 2 digits and reject 5780.13. - step = self.tick_size if self.tick_size > 0 else self.point - return round(round(price / step) * step, self.digits) + # A tick size of 0 means the terminal did not report one; point is used. + return self.tick_size if self.tick_size > 0 else self.point + + def normalize_price(self, price: float) -> float: + return round(round(price / self._step) * self._step, self.digits) def price_on_grid(self, price: float, kind: ErrorKind, what: str) -> Result[float, TradeError]: """``price`` on the tick grid, refused if it is not a usable positive level. - The one place every sent level (entry price, sl, tp) is put on the grid, - so the two ways a positive finite input still goes wrong are checked - once: 1e305 / 1e-5 overflows to inf (round(inf) raises), and 1e-6 - snaps to 0.0, which MT5 reads as "no stop" or "fill at the market". + Every caller-supplied level (an explicit entry price, sl, tp) goes through + here; quote prices come from the terminal already on the grid. The two + ways a positive finite input still goes wrong are checked once: 1e305 / + 1e-5 overflows to inf (round(inf) raises), and 1e-6 snaps to 0.0, which + MT5 reads as "no stop" or "fill at the market". """ - step = self.tick_size if self.tick_size > 0 else self.point - if step <= 0: - # Broken symbol data, refused like a zero volume_step. - return Err(TradeError(kind, f"{self.name} reports no tick size or point")) - if not math.isfinite(price / step): + if not math.isfinite(price / self._step): return Err(TradeError(kind, f"{what} {price} is out of range for {self.name}")) level = self.normalize_price(price) if level <= 0: @@ -69,10 +86,6 @@ def price_on_grid(self, price: float, kind: ErrorKind, what: str) -> Result[floa return Ok(level) def validate_volume(self, volume: float) -> Result[float, TradeError]: - if self.volume_step <= 0: - # Broken symbol data: refusing is the only safe answer, guessing a - # step could send a volume the broker never allowed. - return Err(self._volume_error(volume, "not checkable against")) if volume < self.volume_min - _EPSILON or volume > self.volume_max + _EPSILON: return Err(self._volume_error(volume, "outside")) steps = (volume - self.volume_min) / self.volume_step @@ -103,3 +116,21 @@ def _volume_error(self, volume: float, reason: str) -> TradeError: f"{self.name}: volume {volume} is {reason} " f"[{self.volume_min}, {self.volume_max}] step {self.volume_step}", ) + + +def _problem(spec: SymbolSpec) -> str | None: + def usable(value: float) -> bool: + return isinstance(value, (int, float)) and math.isfinite(value) and value > 0 + + if not usable(spec.point): + return f"point {spec.point!r} is not a positive finite number" + if not (usable(spec.tick_size) or spec.tick_size == 0): + return f"tick size {spec.tick_size!r} is neither 0 nor a positive finite number" + for name, value in (("volume_step", spec.volume_step), ("volume_min", spec.volume_min)): + if not usable(value): + return f"{name} {value!r} is not a positive finite number" + if not (usable(spec.volume_max) and spec.volume_max >= spec.volume_min): + return f"volume_max {spec.volume_max!r} is below volume_min {spec.volume_min!r}" + if spec.digits < 0: + return f"digits {spec.digits!r} is negative" + return None diff --git a/tests/unit/test_input_guards.py b/tests/unit/test_input_guards.py index d6515a3..e988852 100644 --- a/tests/unit/test_input_guards.py +++ b/tests/unit/test_input_guards.py @@ -4,7 +4,6 @@ import math import threading -from dataclasses import replace from decimal import Decimal import pytest @@ -73,15 +72,6 @@ def test_price_that_is_not_a_positive_finite_number_is_refused( assert terminal.sent == [] -def test_a_symbol_reporting_volume_step_zero_is_an_error_not_a_crash( - trader: Trader, terminal: FakeTerminal -) -> None: - terminal.specs["EURUSD"] = replace(EURUSD, volume_step=0.0) - result = trader.open_position("EURUSD", "buy", 0.1) - assert isinstance(result, Err) - assert result.error.kind is ErrorKind.INVALID_VOLUME - - @pytest.mark.parametrize("ticket", [0, -5, True, 1.0, "7"]) def test_a_ticket_that_is_not_a_positive_integer_never_reaches_the_terminal( trader: Trader, terminal: FakeTerminal, ticket: object @@ -270,12 +260,3 @@ def test_stop_parse_reports_a_wrong_kind_as_a_type_error_for_any_value() -> None for value in (0, 5): with pytest.raises(TypeError, match="StopKind"): Stop.parse(value, "points") # type: ignore[arg-type] - - -def test_a_symbol_without_tick_size_or_point_cannot_price_anything( - trader: Trader, terminal: FakeTerminal -) -> None: - terminal.specs["EURUSD"] = replace(EURUSD, tick_size=0.0, point=0.0) - result = trader.place_limit_order("EURUSD", "buy", 0.1, 1.05) - assert isinstance(result, Err) - assert result.error.kind is ErrorKind.INVALID_PRICE diff --git a/tests/unit/test_symbol_data.py b/tests/unit/test_symbol_data.py new file mode 100644 index 0000000..0689554 --- /dev/null +++ b/tests/unit/test_symbol_data.py @@ -0,0 +1,68 @@ +"""Broken symbol data from the terminal must be refused before anything is priced.""" + +from __future__ import annotations + +import math +from dataclasses import replace + +import pytest + +from PythonMetaTrader5 import Stop +from PythonMetaTrader5.adapters.mt5_terminal import MetaTrader5Terminal +from PythonMetaTrader5.application.trader import Trader +from PythonMetaTrader5.domain.errors import ErrorKind +from PythonMetaTrader5.result import Err + +from .fake_mt5 import FakeMT5, symbol_info +from .fakes import EURUSD, FakeTerminal + +BROKEN = [ + {"point": 0.0}, + {"point": math.inf}, + {"point": math.nan}, + {"trade_tick_size": math.inf}, + {"trade_tick_size": -0.1}, + {"volume_step": 0.0}, + {"volume_min": 0.0}, + {"volume_max": 0.001}, + {"digits": -1}, +] +SPEC_FIELD = {"trade_tick_size": "tick_size"} + + +@pytest.mark.parametrize("broken", BROKEN) +def test_the_adapter_refuses_symbol_data_that_cannot_price_an_order( + broken: dict[str, float], +) -> None: + mt5 = FakeMT5() + info = symbol_info() + for key, value in broken.items(): + setattr(info, key, value) + mt5.symbols["EURUSD"] = info + result = MetaTrader5Terminal(mt5).symbol("EURUSD") + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.TERMINAL_ERROR + + +@pytest.mark.parametrize("broken", BROKEN) +def test_a_symbol_spec_with_broken_data_cannot_exist(broken: dict[str, float]) -> None: + fields = {SPEC_FIELD.get(key, key): value for key, value in broken.items()} + with pytest.raises(ValueError, match="EURUSD"): + replace(EURUSD, **fields) # type: ignore[arg-type] + + +def test_absolute_stops_are_checked_before_the_quote_is_fetched( + trader: Trader, terminal: FakeTerminal +) -> None: + # No quote: a stop that can never be valid must not wait for retries first. + terminal.ticks.clear() + result = trader.open_position("EURUSD", "buy", 0.1, sl=1e-6) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_STOPS + + +def test_a_points_take_profit_below_zero_is_refused(trader: Trader, terminal: FakeTerminal) -> None: + result = trader.open_position("EURUSD", "sell", 0.1, tp=Stop.points(10_000_000)) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_STOPS + assert terminal.sent == [] From 098ac0a547c47e1189cae17c4312f859f4af3001 Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 03:20:33 +0100 Subject: [PATCH 22/28] fix: check broken symbol data where it is used, so closes keep working Sixth /code-review high round found a regression in a0f2aba, my own commit. Its constructor invariant on SymbolSpec made the adapter refuse the whole symbol, so close_positions() could no longer flatten a position on a symbol with odd data (volume_step 0, point 0), although closing needs only filling_flags. That is the most safety-critical path, so the invariant is removed and each field is checked where it is used: - price_on_grid refuses a step (tick size, else point) that is not positive and finite. - SymbolSpec.points_to_price refuses a point that is not positive and finite, for points stops only. A symbol with a valid tick size and point 0 can still trade absolute prices. - validate_volume refuses unusable min/max/step as INVALID_VOLUME. That is the error kind callers saw before a0f2aba, not TERMINAL_ERROR. - The adapter refuses NaN and infinite quotes as NO_PRICE. `nan <= 0` is False, so a NaN ask was sent as the order price. - A bad price is again reported before a bad absolute stop. SymbolSpec.check and _problem are removed. A grep over src tests docs *.md finds no remaining use. ADR 0008 records why the whole-spec invariant was rejected. Not changed: absolute stops are snapped once in validate_entry (as a check) and again in Entry.request. That is the same pure function with the same result, and keeping one resolution path avoids a second source of truth for the sent level. RED: on a0f2aba, 24 of the 27 cases in test_symbol_data.py failed, including all 9 close cases. The FloatingPointError case already passed there and pins the ArithmeticError catch. --- CHANGELOG.md | 4 +- docs/adr/0008-refuse-values-mt5-misreads.md | 15 ++- .../adapters/mt5_terminal.py | 28 ++-- src/PythonMetaTrader5/application/entries.py | 9 +- src/PythonMetaTrader5/domain/stops.py | 5 +- src/PythonMetaTrader5/domain/symbol.py | 55 ++++---- tests/unit/test_symbol_data.py | 120 +++++++++++++----- 7 files changed, 144 insertions(+), 92 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 833464e..a31afc6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -61,8 +61,8 @@ Complete rewrite. See [MIGRATION.md](MIGRATION.md) for every behaviour change. positive integers, `volume=True` and non-finite numbers are rejected before sending. - Symbol data that cannot price an order (point 0 or infinite, volume step - 0, ...) is refused as `TERMINAL_ERROR` instead of producing NaN prices or - stops on the entry price. + 0, ...) and NaN or infinite quotes are refused instead of producing NaN + prices or stops on the entry price. Closing still works on such symbols. - `positions(symbol, ticket=...)` applies both filters (MT5 drops the symbol once a ticket is given). - Pending orders on exchange-execution symbols use RETURN filling. diff --git a/docs/adr/0008-refuse-values-mt5-misreads.md b/docs/adr/0008-refuse-values-mt5-misreads.md index fda0122..699ef1f 100644 --- a/docs/adr/0008-refuse-values-mt5-misreads.md +++ b/docs/adr/0008-refuse-values-mt5-misreads.md @@ -65,10 +65,11 @@ well. put on the grid, and it refuses those as well as levels that snap to 0. Quote prices come from the terminal already on the grid. The `Stop` constructors raise `ValueError` on any invalid value. -- Broken symbol data from the terminal is the same problem on the other - side. A point of 0 put a points stop on the entry price, and a point of - inf priced orders at NaN. `SymbolSpec` therefore has an invariant: point, - volume step and volume min must be positive and finite, the tick size must - be 0 or positive and finite, and volume max must not be below volume min. - The adapter turns a violation into `Err(TERMINAL_ERROR)` through - `SymbolSpec.check`. +- Broken data from the terminal is the same problem on the other side. A + point of 0 put a points stop on the entry price, and a point or tick size + of inf priced orders at NaN. Each field is checked where it is used: + `price_on_grid` checks the step, `points_to_price` the point, + `validate_volume` the volume limits, and the adapter refuses NaN and + infinite quotes as `NO_PRICE`. We rejected an invariant on the whole + `SymbolSpec`. It made a position on such a symbol impossible to close, + although closing needs only the filling flags. diff --git a/src/PythonMetaTrader5/adapters/mt5_terminal.py b/src/PythonMetaTrader5/adapters/mt5_terminal.py index cd96eb4..cc46d06 100644 --- a/src/PythonMetaTrader5/adapters/mt5_terminal.py +++ b/src/PythonMetaTrader5/adapters/mt5_terminal.py @@ -8,6 +8,7 @@ import functools import importlib +import math import threading from collections.abc import Callable from typing import Any, ParamSpec, TypeVar @@ -137,25 +138,26 @@ def symbol(self, name: str) -> Result[SymbolSpec, TradeError]: f"{name!r} cannot be added to Market Watch: {self._last_error()}", ) ) - return SymbolSpec.check( - { - "name": info.name, - "digits": int(info.digits), - "point": float(info.point), - "tick_size": float(info.trade_tick_size), - "volume_min": float(info.volume_min), - "volume_max": float(info.volume_max), - "volume_step": float(info.volume_step), - "filling_flags": int(info.filling_mode), - "exchange_execution": int(info.trade_exemode) == self._exchange_execution, - } + return Ok( + SymbolSpec( + name=info.name, + digits=int(info.digits), + point=float(info.point), + tick_size=float(info.trade_tick_size), + volume_min=float(info.volume_min), + volume_max=float(info.volume_max), + volume_step=float(info.volume_step), + filling_flags=int(info.filling_mode), + exchange_execution=int(info.trade_exemode) == self._exchange_execution, + ) ) @_serialized def tick(self, name: str) -> Result[Tick, TradeError]: tick = self._mt5.symbol_info_tick(name) # A zero side means no quote yet; trading at price 0 must never be attempted. - if tick is None or tick.bid <= 0 or tick.ask <= 0: + # NaN and inf are refused too: `nan <= 0` is False and would send price NaN. + if tick is None or not all(math.isfinite(p) and p > 0 for p in (tick.bid, tick.ask)): return Err(TradeError(ErrorKind.NO_PRICE, f"no quote for {name!r}")) return Ok(Tick(bid=float(tick.bid), ask=float(tick.ask))) diff --git a/src/PythonMetaTrader5/application/entries.py b/src/PythonMetaTrader5/application/entries.py index 49aaf73..02b82f4 100644 --- a/src/PythonMetaTrader5/application/entries.py +++ b/src/PythonMetaTrader5/application/entries.py @@ -109,15 +109,16 @@ def _quote_free_levels( # Absolute stops do not depend on the quote, so they are checked here, before # the first tick request: otherwise a stop that can never be valid would sit # through the NO_PRICE retries of a symbol without quotes first. + # The price first, so a bad price is still reported before a bad stop. + level = None if price is None else spec.price_on_grid(price, ErrorKind.INVALID_PRICE, "price") + if isinstance(level, Err): + return level for name, stop in (("sl", sl), ("tp", tp)): if stop is not None and stop.kind is StopKind.PRICE: checked = spec.price_on_grid(stop.value, ErrorKind.INVALID_STOPS, name) if isinstance(checked, Err): return checked - if price is None: - return Ok(None) - level = spec.price_on_grid(price, ErrorKind.INVALID_PRICE, "price") - return level if isinstance(level, Err) else Ok(level.value) + return Ok(None if level is None else level.value) def _caller_values( diff --git a/src/PythonMetaTrader5/domain/stops.py b/src/PythonMetaTrader5/domain/stops.py index d5161c0..6e7d3df 100644 --- a/src/PythonMetaTrader5/domain/stops.py +++ b/src/PythonMetaTrader5/domain/stops.py @@ -64,7 +64,10 @@ def _resolve( # level below zero (a long points distance) or off the grid is refused. level = self.value if self.kind is StopKind.POINTS: - level = reference + direction * self.value * spec.point + distance = spec.points_to_price(self.value) + if isinstance(distance, Err): + return distance + level = reference + direction * distance.value return spec.price_on_grid(level, ErrorKind.INVALID_STOPS, what) diff --git a/src/PythonMetaTrader5/domain/symbol.py b/src/PythonMetaTrader5/domain/symbol.py index 6251561..7b9c0d5 100644 --- a/src/PythonMetaTrader5/domain/symbol.py +++ b/src/PythonMetaTrader5/domain/symbol.py @@ -43,21 +43,10 @@ class SymbolSpec: # market execution and send limits that cancel instead of resting. exchange_execution: bool - def __post_init__(self) -> None: - # The invariant lives here so pricing code never meets a zero, NaN or - # infinite step: point 0 put a points stop on the entry price, point inf - # priced orders at NaN. Raised, not returned: such a spec cannot exist; - # the adapter turns terminal data into a Result through SymbolSpec.check. - problem = _problem(self) - if problem is not None: - raise ValueError(f"{self.name}: {problem}") - - @staticmethod - def check(spec_fields: dict[str, object]) -> Result[SymbolSpec, TradeError]: - try: - return Ok(SymbolSpec(**spec_fields)) # type: ignore[arg-type] - except ValueError as error: - return Err(TradeError(ErrorKind.TERMINAL_ERROR, f"broken symbol data: {error}")) + # Broken terminal data (a point of 0 or inf, a volume step of 0) is checked + # where each field is used, not refused for the whole spec: closing a + # position needs only filling_flags, and a symbol with odd data must still be + # closable. A constructor invariant was tried and dropped for that reason. @property def _step(self) -> float: @@ -78,6 +67,8 @@ def price_on_grid(self, price: float, kind: ErrorKind, what: str) -> Result[floa 1e-5 overflows to inf (round(inf) raises), and 1e-6 snaps to 0.0, which MT5 reads as "no stop" or "fill at the market". """ + if not _usable(self._step): + return Err(TradeError(kind, f"{self.name} reports no usable tick size or point")) if not math.isfinite(price / self._step): return Err(TradeError(kind, f"{what} {price} is out of range for {self.name}")) level = self.normalize_price(price) @@ -85,7 +76,18 @@ def price_on_grid(self, price: float, kind: ErrorKind, what: str) -> Result[floa return Err(TradeError(kind, f"{what} {price} snaps to {level} on {self.name}")) return Ok(level) + def points_to_price(self, points: float) -> Result[float, TradeError]: + # point 0 would put a points stop on the entry price, point inf at NaN. + if not _usable(self.point): + message = f"{self.name} reports point {self.point!r}; points stops need a positive one" + return Err(TradeError(ErrorKind.INVALID_STOPS, message)) + return Ok(points * self.point) + def validate_volume(self, volume: float) -> Result[float, TradeError]: + limits = (self.volume_min, self.volume_max, self.volume_step) + if not all(_usable(x) for x in limits) or self.volume_max < self.volume_min: + # Guessing a step or limit could send a volume the broker never allowed. + return Err(self._volume_error(volume, "not checkable against")) if volume < self.volume_min - _EPSILON or volume > self.volume_max + _EPSILON: return Err(self._volume_error(volume, "outside")) steps = (volume - self.volume_min) / self.volume_step @@ -118,19 +120,10 @@ def _volume_error(self, volume: float, reason: str) -> TradeError: ) -def _problem(spec: SymbolSpec) -> str | None: - def usable(value: float) -> bool: - return isinstance(value, (int, float)) and math.isfinite(value) and value > 0 - - if not usable(spec.point): - return f"point {spec.point!r} is not a positive finite number" - if not (usable(spec.tick_size) or spec.tick_size == 0): - return f"tick size {spec.tick_size!r} is neither 0 nor a positive finite number" - for name, value in (("volume_step", spec.volume_step), ("volume_min", spec.volume_min)): - if not usable(value): - return f"{name} {value!r} is not a positive finite number" - if not (usable(spec.volume_max) and spec.volume_max >= spec.volume_min): - return f"volume_max {spec.volume_max!r} is below volume_min {spec.volume_min!r}" - if spec.digits < 0: - return f"digits {spec.digits!r} is negative" - return None +def _usable(value: float) -> bool: + return ( + isinstance(value, (int, float)) + and not isinstance(value, bool) + and math.isfinite(value) + and value > 0 + ) diff --git a/tests/unit/test_symbol_data.py b/tests/unit/test_symbol_data.py index 0689554..c6c4c61 100644 --- a/tests/unit/test_symbol_data.py +++ b/tests/unit/test_symbol_data.py @@ -1,9 +1,11 @@ -"""Broken symbol data from the terminal must be refused before anything is priced.""" +"""Broken data from the terminal must never price an order, and never block a close.""" from __future__ import annotations import math from dataclasses import replace +from fractions import Fraction +from types import SimpleNamespace import pytest @@ -11,44 +13,94 @@ from PythonMetaTrader5.adapters.mt5_terminal import MetaTrader5Terminal from PythonMetaTrader5.application.trader import Trader from PythonMetaTrader5.domain.errors import ErrorKind -from PythonMetaTrader5.result import Err - -from .fake_mt5 import FakeMT5, symbol_info -from .fakes import EURUSD, FakeTerminal - -BROKEN = [ - {"point": 0.0}, - {"point": math.inf}, - {"point": math.nan}, - {"trade_tick_size": math.inf}, - {"trade_tick_size": -0.1}, - {"volume_step": 0.0}, - {"volume_min": 0.0}, - {"volume_max": 0.001}, - {"digits": -1}, -] -SPEC_FIELD = {"trade_tick_size": "tick_size"} - - -@pytest.mark.parametrize("broken", BROKEN) -def test_the_adapter_refuses_symbol_data_that_cannot_price_an_order( - broken: dict[str, float], +from PythonMetaTrader5.result import Err, Ok + +from .fake_mt5 import FakeMT5 +from .fakes import EURUSD, FakeTerminal, make_position + +BROKEN_STEP = [{"point": 0.0, "tick_size": 0.0}, {"point": math.inf, "tick_size": 0.0}] +BROKEN_STEP += [{"tick_size": math.inf}, {"point": math.nan, "tick_size": 0.0}] +BROKEN_VOLUME = [{"volume_step": 0.0}, {"volume_min": 0.0}, {"volume_max": 0.001}] +BROKEN_VOLUME += [{"volume_max": math.nan}, {"volume_step": math.inf}] + + +@pytest.mark.parametrize("broken", BROKEN_STEP) +def test_a_symbol_without_a_usable_step_prices_nothing( + trader: Trader, terminal: FakeTerminal, broken: dict[str, float] +) -> None: + terminal.specs["EURUSD"] = replace(EURUSD, **broken) + for result, kind in ( + (trader.place_limit_order("EURUSD", "buy", 0.1, 1.05), ErrorKind.INVALID_PRICE), + (trader.open_position("EURUSD", "buy", 0.1, sl=1.0), ErrorKind.INVALID_STOPS), + ): + assert isinstance(result, Err) + assert result.error.kind is kind + assert terminal.sent == [] + + +@pytest.mark.parametrize("point", [0.0, math.inf, math.nan]) +def test_points_stops_need_a_usable_point_but_prices_do_not( + trader: Trader, terminal: FakeTerminal, point: float +) -> None: + # A tick size alone is enough for absolute prices; only points need `point`. + terminal.specs["EURUSD"] = replace(EURUSD, point=point) + refused = trader.open_position("EURUSD", "buy", 0.1, sl=Stop.points(1000)) + assert isinstance(refused, Err) + assert refused.error.kind is ErrorKind.INVALID_STOPS + assert terminal.sent == [] + assert isinstance(trader.open_position("EURUSD", "buy", 0.1, sl=1.09), Ok) + + +@pytest.mark.parametrize("broken", BROKEN_VOLUME) +def test_unusable_volume_limits_refuse_every_entry( + trader: Trader, terminal: FakeTerminal, broken: dict[str, float] +) -> None: + terminal.specs["EURUSD"] = replace(EURUSD, **broken) + result = trader.open_position("EURUSD", "buy", 0.1) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_VOLUME + assert terminal.sent == [] + + +@pytest.mark.parametrize("broken", [*BROKEN_STEP, *BROKEN_VOLUME]) +def test_a_position_on_a_symbol_with_broken_data_can_still_be_closed( + trader: Trader, terminal: FakeTerminal, broken: dict[str, float] ) -> None: + terminal.specs["EURUSD"] = replace(EURUSD, **broken) + terminal.open_positions = [make_position(1)] + closed = trader.close_positions("EURUSD") + assert isinstance(closed, Ok) + assert len(closed.value) == 1 + + +@pytest.mark.parametrize("quote", [math.nan, math.inf]) +def test_a_nan_or_infinite_quote_is_no_price(quote: float) -> None: mt5 = FakeMT5() - info = symbol_info() - for key, value in broken.items(): - setattr(info, key, value) - mt5.symbols["EURUSD"] = info - result = MetaTrader5Terminal(mt5).symbol("EURUSD") + mt5.ticks["EURUSD"] = SimpleNamespace(bid=1.1, ask=quote) + result = MetaTrader5Terminal(mt5).tick("EURUSD") + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.NO_PRICE + + +class _OutOfRange(Fraction): + # Stands in for a numpy longdouble under np.seterr(over="raise"). + def __float__(self) -> float: + raise FloatingPointError("overflow") + + +def test_a_number_whose_float_conversion_overflows_is_refused_not_raised( + trader: Trader, terminal: FakeTerminal +) -> None: + result = trader.open_position("EURUSD", "buy", _OutOfRange(1, 10)) assert isinstance(result, Err) - assert result.error.kind is ErrorKind.TERMINAL_ERROR + assert result.error.kind is ErrorKind.INVALID_VOLUME + assert terminal.sent == [] -@pytest.mark.parametrize("broken", BROKEN) -def test_a_symbol_spec_with_broken_data_cannot_exist(broken: dict[str, float]) -> None: - fields = {SPEC_FIELD.get(key, key): value for key, value in broken.items()} - with pytest.raises(ValueError, match="EURUSD"): - replace(EURUSD, **fields) # type: ignore[arg-type] +def test_a_bad_price_is_reported_before_a_bad_stop(trader: Trader) -> None: + result = trader.place_limit_order("EURUSD", "buy", 0.1, 1e-6, sl=1e-6) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_PRICE def test_absolute_stops_are_checked_before_the_quote_is_fetched( From a11a6180fdc8acd94877dd96d73e42bef25c0f10 Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 03:23:31 +0100 Subject: [PATCH 23/28] fix: broken symbol data is a TERMINAL_ERROR on every entry, never on a close Seventh /code-review high round, on 098ac0a: - A NaN or negative tick size silently fell back to `point`, and negative digits rounded to tens (5785.25 -> 5790.0). Both have been checked since a0f2aba removed the constructor invariant. - A market order without price or stops on a symbol with no usable step was still sent, because it never reaches price_on_grid. Every entry now calls SymbolSpec.check_tradable() first, which checks tick size, step, digits and volume limits. Closing never calls it. - Broken data was reported as INVALID_PRICE / INVALID_STOPS / INVALID_VOLUME, which blames the caller, so a bot would drop signals instead of escalating. It is now TERMINAL_ERROR with "broken symbol data" in the message. - normalize_price is folded into price_on_grid. As a public method it raised ZeroDivisionError or returned NaN on broken data. A grep over src tests docs README.md MIGRATION.md CHANGELOG.md finds no remaining use. - _usable drops runtime type checks the float-typed fields never needed. - An adapter-level test pins that broken symbol_info is passed on, not refused, so the a0f2aba close regression cannot come back through the adapter. CHANGELOG and ADR 0008 now describe what is actually refused. RED: on 098ac0a, 16 of the 34 cases in test_symbol_data.py failed (the new pricing cases, the market order without stops, and the error kinds). --- CHANGELOG.md | 8 +- docs/adr/0008-refuse-values-mt5-misreads.md | 15 ++-- src/PythonMetaTrader5/application/entries.py | 5 ++ src/PythonMetaTrader5/domain/symbol.py | 81 ++++++++++++-------- tests/unit/test_symbol.py | 24 ++++-- tests/unit/test_symbol_data.py | 28 +++++-- 6 files changed, 108 insertions(+), 53 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a31afc6..19c8ffa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -60,9 +60,11 @@ Complete rewrite. See [MIGRATION.md](MIGRATION.md) for every behaviour change. - `sl=0` / `tp=0`, stops that resolve to zero or below, tickets that are not positive integers, `volume=True` and non-finite numbers are rejected before sending. -- Symbol data that cannot price an order (point 0 or infinite, volume step - 0, ...) and NaN or infinite quotes are refused instead of producing NaN - prices or stops on the entry price. Closing still works on such symbols. +- Entries on a symbol whose data cannot price an order (no usable tick size + or point, a NaN tick size, negative digits, volume step 0, ...) return + `TERMINAL_ERROR` instead of sending NaN prices or stops on the entry price. + Points stops additionally need a usable `point`. NaN or infinite quotes are + `NO_PRICE`. Closing still works on such symbols. - `positions(symbol, ticket=...)` applies both filters (MT5 drops the symbol once a ticket is given). - Pending orders on exchange-execution symbols use RETURN filling. diff --git a/docs/adr/0008-refuse-values-mt5-misreads.md b/docs/adr/0008-refuse-values-mt5-misreads.md index 699ef1f..37be014 100644 --- a/docs/adr/0008-refuse-values-mt5-misreads.md +++ b/docs/adr/0008-refuse-values-mt5-misreads.md @@ -67,9 +67,12 @@ well. constructors raise `ValueError` on any invalid value. - Broken data from the terminal is the same problem on the other side. A point of 0 put a points stop on the entry price, and a point or tick size - of inf priced orders at NaN. Each field is checked where it is used: - `price_on_grid` checks the step, `points_to_price` the point, - `validate_volume` the volume limits, and the adapter refuses NaN and - infinite quotes as `NO_PRICE`. We rejected an invariant on the whole - `SymbolSpec`. It made a position on such a symbol impossible to close, - although closing needs only the filling flags. + of inf priced orders at NaN. These are the broker's fault, so they come + back as `TERMINAL_ERROR`, not as `INVALID_*`, which would blame the + caller. Every entry calls `SymbolSpec.check_tradable()` (tick size, step, + digits, volume limits), including market orders without stops. + `points_to_price` also checks `point`, which only points stops need. The + adapter refuses NaN and infinite quotes as `NO_PRICE`. Closing never runs + these checks. We rejected an invariant on the whole `SymbolSpec`: it made a + position on such a symbol impossible to close, although closing needs only + the filling flags. diff --git a/src/PythonMetaTrader5/application/entries.py b/src/PythonMetaTrader5/application/entries.py index 02b82f4..1193626 100644 --- a/src/PythonMetaTrader5/application/entries.py +++ b/src/PythonMetaTrader5/application/entries.py @@ -109,6 +109,11 @@ def _quote_free_levels( # Absolute stops do not depend on the quote, so they are checked here, before # the first tick request: otherwise a stop that can never be valid would sit # through the NO_PRICE retries of a symbol without quotes first. + # Broken pricing data refuses every entry, market orders without stops too: + # those never reach price_on_grid. + tradable = spec.check_tradable() + if isinstance(tradable, Err): + return tradable # The price first, so a bad price is still reported before a bad stop. level = None if price is None else spec.price_on_grid(price, ErrorKind.INVALID_PRICE, "price") if isinstance(level, Err): diff --git a/src/PythonMetaTrader5/domain/symbol.py b/src/PythonMetaTrader5/domain/symbol.py index 7b9c0d5..901db06 100644 --- a/src/PythonMetaTrader5/domain/symbol.py +++ b/src/PythonMetaTrader5/domain/symbol.py @@ -43,20 +43,16 @@ class SymbolSpec: # market execution and send limits that cancel instead of resting. exchange_execution: bool - # Broken terminal data (a point of 0 or inf, a volume step of 0) is checked - # where each field is used, not refused for the whole spec: closing a - # position needs only filling_flags, and a symbol with odd data must still be - # closable. A constructor invariant was tried and dropped for that reason. + # Broken terminal data (a point of 0 or inf, a NaN tick size, a volume step + # of 0) is reported as TERMINAL_ERROR: it is the broker's fault, and a bot + # must not file it as a bad signal. It is checked on use rather than refused + # for the whole spec, because closing a position needs only filling_flags + # and must keep working on such a symbol (a constructor invariant was tried + # and dropped for exactly that). Entries call check_tradable() first. - @property - def _step(self) -> float: - # A price must sit on the tick grid, not merely have `digits` decimals: - # index CFDs often have tick 0.25 with 2 digits and reject 5780.13. - # A tick size of 0 means the terminal did not report one; point is used. - return self.tick_size if self.tick_size > 0 else self.point - - def normalize_price(self, price: float) -> float: - return round(round(price / self._step) * self._step, self.digits) + def check_tradable(self) -> Result[None, TradeError]: + problem = self._pricing_problem() or self._volume_problem() + return Ok(None) if problem is None else Err(self._data_error(problem)) def price_on_grid(self, price: float, kind: ErrorKind, what: str) -> Result[float, TradeError]: """``price`` on the tick grid, refused if it is not a usable positive level. @@ -67,27 +63,30 @@ def price_on_grid(self, price: float, kind: ErrorKind, what: str) -> Result[floa 1e-5 overflows to inf (round(inf) raises), and 1e-6 snaps to 0.0, which MT5 reads as "no stop" or "fill at the market". """ - if not _usable(self._step): - return Err(TradeError(kind, f"{self.name} reports no usable tick size or point")) - if not math.isfinite(price / self._step): + problem = self._pricing_problem() + if problem is not None: + return Err(self._data_error(problem)) + # A price must sit on the tick grid, not merely have `digits` decimals: + # index CFDs often have tick 0.25 with 2 digits and reject 5780.13. + step = self._step + if not math.isfinite(price / step): return Err(TradeError(kind, f"{what} {price} is out of range for {self.name}")) - level = self.normalize_price(price) + level = round(round(price / step) * step, self.digits) if level <= 0: return Err(TradeError(kind, f"{what} {price} snaps to {level} on {self.name}")) return Ok(level) def points_to_price(self, points: float) -> Result[float, TradeError]: - # point 0 would put a points stop on the entry price, point inf at NaN. + # Only points stops need `point`: a symbol with a valid tick size and a + # point of 0 still trades absolute prices. if not _usable(self.point): - message = f"{self.name} reports point {self.point!r}; points stops need a positive one" - return Err(TradeError(ErrorKind.INVALID_STOPS, message)) + return Err(self._data_error(f"point {self.point!r} cannot measure a points stop")) return Ok(points * self.point) def validate_volume(self, volume: float) -> Result[float, TradeError]: - limits = (self.volume_min, self.volume_max, self.volume_step) - if not all(_usable(x) for x in limits) or self.volume_max < self.volume_min: - # Guessing a step or limit could send a volume the broker never allowed. - return Err(self._volume_error(volume, "not checkable against")) + problem = self._volume_problem() + if problem is not None: + return Err(self._data_error(problem)) if volume < self.volume_min - _EPSILON or volume > self.volume_max + _EPSILON: return Err(self._volume_error(volume, "outside")) steps = (volume - self.volume_min) / self.volume_step @@ -96,6 +95,33 @@ def validate_volume(self, volume: float) -> Result[float, TradeError]: snapped = self.volume_min + round(steps) * self.volume_step return Ok(round(snapped, _VOLUME_DECIMALS)) + @property + def _step(self) -> float: + # A tick size of 0 means the terminal did not report one; point is used. + return self.tick_size if self.tick_size > 0 else self.point + + def _pricing_problem(self) -> str | None: + # Checked before _step is used: a NaN or negative tick size would + # otherwise fall back to point without anyone noticing. + if not (self.tick_size == 0 or _usable(self.tick_size)): + return f"tick size {self.tick_size!r} is neither 0 nor positive and finite" + if not _usable(self._step): + return f"no usable tick size or point (point {self.point!r})" + if self.digits < 0: + return f"digits {self.digits} is negative" + return None + + def _volume_problem(self) -> str | None: + limits = (self.volume_min, self.volume_max, self.volume_step) + if not all(_usable(x) for x in limits): + return f"volume min/max/step {limits} are not all positive and finite" + if self.volume_max < self.volume_min: + return f"volume_max {self.volume_max} is below volume_min {self.volume_min}" + return None + + def _data_error(self, problem: str) -> TradeError: + return TradeError(ErrorKind.TERMINAL_ERROR, f"{self.name}: broken symbol data: {problem}") + def market_filling(self) -> Filling: # FOK first: a webhook bot asking for 1 lot must get 1 lot or nothing. # IOC could silently leave it with a partial fill it never asked for. @@ -121,9 +147,4 @@ def _volume_error(self, volume: float, reason: str) -> TradeError: def _usable(value: float) -> bool: - return ( - isinstance(value, (int, float)) - and not isinstance(value, bool) - and math.isfinite(value) - and value > 0 - ) + return math.isfinite(value) and value > 0 diff --git a/tests/unit/test_symbol.py b/tests/unit/test_symbol.py index 2ed9c01..ae2bd8a 100644 --- a/tests/unit/test_symbol.py +++ b/tests/unit/test_symbol.py @@ -21,18 +21,22 @@ def eurusd(**overrides: object) -> SymbolSpec: return SymbolSpec(**fields) # type: ignore[arg-type] -def test_normalize_price_rounds_to_tick_without_float_noise() -> None: - assert eurusd().normalize_price(1.123456) == 1.12346 - assert eurusd().normalize_price(1.1) == 1.1 +def on_grid(spec: SymbolSpec, price: float) -> object: + return spec.price_on_grid(price, ErrorKind.INVALID_PRICE, "price") -def test_normalize_price_uses_tick_size_coarser_than_point() -> None: +def test_prices_snap_to_the_tick_without_float_noise() -> None: + assert on_grid(eurusd(), 1.123456) == Ok(1.12346) + assert on_grid(eurusd(), 1.1) == Ok(1.1) + + +def test_prices_use_a_tick_size_coarser_than_point() -> None: index = eurusd(name="US500", digits=2, point=0.01, tick_size=0.25) - assert index.normalize_price(5780.13) == 5780.25 + assert on_grid(index, 5780.13) == Ok(5780.25) -def test_normalize_price_falls_back_to_point_when_tick_size_missing() -> None: - assert eurusd(tick_size=0.0).normalize_price(1.123456) == 1.12346 +def test_prices_fall_back_to_point_when_tick_size_missing() -> None: + assert on_grid(eurusd(tick_size=0.0), 1.123456) == Ok(1.12346) @pytest.mark.parametrize("volume", [0.01, 0.1, 0.37, 100.0]) @@ -59,3 +63,9 @@ def test_invalid_volume_is_rejected(volume: float) -> None: ) def test_market_filling_prefers_fill_or_kill(flags: int, expected: Filling) -> None: assert eurusd(filling_flags=flags).market_filling() is expected + + +def test_pricing_on_broken_data_is_a_terminal_error_even_when_called_directly() -> None: + result = on_grid(eurusd(point=0.0, tick_size=0.0), 1.1) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.TERMINAL_ERROR diff --git a/tests/unit/test_symbol_data.py b/tests/unit/test_symbol_data.py index c6c4c61..f94413d 100644 --- a/tests/unit/test_symbol_data.py +++ b/tests/unit/test_symbol_data.py @@ -15,11 +15,12 @@ from PythonMetaTrader5.domain.errors import ErrorKind from PythonMetaTrader5.result import Err, Ok -from .fake_mt5 import FakeMT5 +from .fake_mt5 import FakeMT5, symbol_info from .fakes import EURUSD, FakeTerminal, make_position BROKEN_STEP = [{"point": 0.0, "tick_size": 0.0}, {"point": math.inf, "tick_size": 0.0}] BROKEN_STEP += [{"tick_size": math.inf}, {"point": math.nan, "tick_size": 0.0}] +BROKEN_STEP += [{"tick_size": math.nan}, {"tick_size": -0.25}, {"digits": -1}] BROKEN_VOLUME = [{"volume_step": 0.0}, {"volume_min": 0.0}, {"volume_max": 0.001}] BROKEN_VOLUME += [{"volume_max": math.nan}, {"volume_step": math.inf}] @@ -29,12 +30,14 @@ def test_a_symbol_without_a_usable_step_prices_nothing( trader: Trader, terminal: FakeTerminal, broken: dict[str, float] ) -> None: terminal.specs["EURUSD"] = replace(EURUSD, **broken) - for result, kind in ( - (trader.place_limit_order("EURUSD", "buy", 0.1, 1.05), ErrorKind.INVALID_PRICE), - (trader.open_position("EURUSD", "buy", 0.1, sl=1.0), ErrorKind.INVALID_STOPS), + for result in ( + trader.place_limit_order("EURUSD", "buy", 0.1, 1.05), + trader.open_position("EURUSD", "buy", 0.1, sl=1.0), + trader.open_position("EURUSD", "buy", 0.1), # no price, no stops ): assert isinstance(result, Err) - assert result.error.kind is kind + # The broker's data is at fault, not the caller's input. + assert result.error.kind is ErrorKind.TERMINAL_ERROR assert terminal.sent == [] @@ -46,7 +49,7 @@ def test_points_stops_need_a_usable_point_but_prices_do_not( terminal.specs["EURUSD"] = replace(EURUSD, point=point) refused = trader.open_position("EURUSD", "buy", 0.1, sl=Stop.points(1000)) assert isinstance(refused, Err) - assert refused.error.kind is ErrorKind.INVALID_STOPS + assert refused.error.kind is ErrorKind.TERMINAL_ERROR assert terminal.sent == [] assert isinstance(trader.open_position("EURUSD", "buy", 0.1, sl=1.09), Ok) @@ -58,7 +61,7 @@ def test_unusable_volume_limits_refuse_every_entry( terminal.specs["EURUSD"] = replace(EURUSD, **broken) result = trader.open_position("EURUSD", "buy", 0.1) assert isinstance(result, Err) - assert result.error.kind is ErrorKind.INVALID_VOLUME + assert result.error.kind is ErrorKind.TERMINAL_ERROR assert terminal.sent == [] @@ -73,6 +76,17 @@ def test_a_position_on_a_symbol_with_broken_data_can_still_be_closed( assert len(closed.value) == 1 +def test_the_adapter_passes_broken_symbol_data_on_so_closes_still_work() -> None: + # Refusing it in the adapter would block close_positions (the a0f2aba bug). + mt5 = FakeMT5() + info = symbol_info() + info.point, info.trade_tick_size, info.volume_step = 0.0, 0.0, 0.0 + mt5.symbols["EURUSD"] = info + spec = MetaTrader5Terminal(mt5).symbol("EURUSD") + assert isinstance(spec, Ok) + assert isinstance(spec.value.check_tradable(), Err) + + @pytest.mark.parametrize("quote", [math.nan, math.inf]) def test_a_nan_or_infinite_quote_is_no_price(quote: float) -> None: mt5 = FakeMT5() From 880ca9c32eeb1089f1a31666e08df31aa7b88aa7 Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 12:23:24 +0100 Subject: [PATCH 24/28] fix: BROKEN_SYMBOL_DATA kind; tradability checked right after the symbol lookup Eighth /code-review high round, on a11a618. Only findings that send an unasked order, block a close, raise out of a Result boundary, or regress this branch are fixed here. The rest are listed in the PR as debt. - Broken symbol data came back as TERMINAL_ERROR, which ADR 0003 defines as "never sent, safe to resend". A bot following that rule would resend forever, because broken data does not clear. It now has its own kind, BROKEN_SYMBOL_DATA (escalate, don't retry). The README error table says so. - check_tradable ran after validate_volume, so broken data plus an out-of-range volume came back as the caller's INVALID_VOLUME. It now runs right after the symbol lookup (_tradable_spec), the one place every entry passes through. - _usable lost its type check in a11a618, so a hand-built spec with point=None raised TypeError out of check_tradable. The check is restored. RED: against a11a618's src, 18 of the 54 cases in test_symbol_data.py and test_symbol.py failed (the new kind, the precedence and the None point). --- CHANGELOG.md | 2 +- README.md | 1 + docs/adr/0008-refuse-values-mt5-misreads.md | 7 ++-- src/PythonMetaTrader5/application/entries.py | 19 ++++++---- src/PythonMetaTrader5/domain/errors.py | 4 +++ src/PythonMetaTrader5/domain/symbol.py | 22 ++++++++---- tests/unit/test_symbol.py | 2 +- tests/unit/test_symbol_data.py | 38 ++++++++++++++++++-- 8 files changed, 74 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 19c8ffa..0a6e231 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -62,7 +62,7 @@ Complete rewrite. See [MIGRATION.md](MIGRATION.md) for every behaviour change. sending. - Entries on a symbol whose data cannot price an order (no usable tick size or point, a NaN tick size, negative digits, volume step 0, ...) return - `TERMINAL_ERROR` instead of sending NaN prices or stops on the entry price. + `BROKEN_SYMBOL_DATA` instead of sending NaN prices or stops on the entry price. Points stops additionally need a usable `point`. NaN or infinite quotes are `NO_PRICE`. Closing still works on such symbols. - `positions(symbol, ticket=...)` applies both filters (MT5 drops the symbol diff --git a/README.md b/README.md index 66b8ca9..5470e08 100644 --- a/README.md +++ b/README.md @@ -135,6 +135,7 @@ deviation=10, retry=None) -> Result[Trader, TradeError]` | requote, price changed, no quotes, too many requests | retried with a fresh quote, up to `RetryPolicy.attempts` (default 3, 0.5 s apart), then `RETRIES_EXHAUSTED` | | timeout, no connection, or `order_send` lost in IPC | `OUTCOME_UNKNOWN`, never retried: check `positions()` first | | anything else | the matching `ErrorKind`, returned at once | +| refused before sending: the terminal's symbol data cannot price an order (point 0, NaN tick size, volume step 0, ...) | `BROKEN_SYMBOL_DATA`, the same on every resend: escalate, don't retry. Closing still works on such symbols | ```python from PythonMetaTrader5 import RetryPolicy, connect diff --git a/docs/adr/0008-refuse-values-mt5-misreads.md b/docs/adr/0008-refuse-values-mt5-misreads.md index 37be014..3189cd2 100644 --- a/docs/adr/0008-refuse-values-mt5-misreads.md +++ b/docs/adr/0008-refuse-values-mt5-misreads.md @@ -67,9 +67,10 @@ well. constructors raise `ValueError` on any invalid value. - Broken data from the terminal is the same problem on the other side. A point of 0 put a points stop on the entry price, and a point or tick size - of inf priced orders at NaN. These are the broker's fault, so they come - back as `TERMINAL_ERROR`, not as `INVALID_*`, which would blame the - caller. Every entry calls `SymbolSpec.check_tradable()` (tick size, step, + of inf priced orders at NaN. These are the broker's fault and do not clear + on a resend, so they come back as `BROKEN_SYMBOL_DATA`. `INVALID_*` would + blame the caller, and `TERMINAL_ERROR` means "never sent, safe to resend" + (ADR 0003), which would loop. Every entry calls `SymbolSpec.check_tradable()` (tick size, step, digits, volume limits), including market orders without stops. `points_to_price` also checks `point`, which only points stops need. The adapter refuses NaN and infinite quotes as `NO_PRICE`. Closing never runs diff --git a/src/PythonMetaTrader5/application/entries.py b/src/PythonMetaTrader5/application/entries.py index 1193626..d4eb121 100644 --- a/src/PythonMetaTrader5/application/entries.py +++ b/src/PythonMetaTrader5/application/entries.py @@ -88,7 +88,7 @@ def validate_entry( amount = positive_number(volume, ErrorKind.INVALID_VOLUME, "volume") if isinstance(amount, Err): return amount - spec = terminal.symbol(symbol) + spec = _tradable_spec(terminal, symbol) if isinstance(spec, Err): return spec lots = spec.value.validate_volume(amount.value) @@ -103,17 +103,24 @@ def validate_entry( ) +def _tradable_spec(terminal: Terminal, symbol: str) -> Result[SymbolSpec, TradeError]: + # Checked right after the lookup, before any caller value is judged against + # the spec: broken broker data must not come back as the caller's + # INVALID_VOLUME. It covers market orders without stops too, which never + # reach price_on_grid. Closing never calls this. + spec = terminal.symbol(symbol) + if isinstance(spec, Err): + return spec + tradable = spec.value.check_tradable() + return tradable if isinstance(tradable, Err) else spec + + def _quote_free_levels( spec: SymbolSpec, price: float | None, sl: Stop | None, tp: Stop | None ) -> Result[float | None, TradeError]: # Absolute stops do not depend on the quote, so they are checked here, before # the first tick request: otherwise a stop that can never be valid would sit # through the NO_PRICE retries of a symbol without quotes first. - # Broken pricing data refuses every entry, market orders without stops too: - # those never reach price_on_grid. - tradable = spec.check_tradable() - if isinstance(tradable, Err): - return tradable # The price first, so a bad price is still reported before a bad stop. level = None if price is None else spec.price_on_grid(price, ErrorKind.INVALID_PRICE, "price") if isinstance(level, Err): diff --git a/src/PythonMetaTrader5/domain/errors.py b/src/PythonMetaTrader5/domain/errors.py index 166da51..980ca33 100644 --- a/src/PythonMetaTrader5/domain/errors.py +++ b/src/PythonMetaTrader5/domain/errors.py @@ -30,6 +30,10 @@ class ErrorKind(Enum): SYMBOL_NOT_FOUND = "symbol_not_found" NO_PRICE = "no_price" TERMINAL_ERROR = "terminal_error" + # The terminal reports symbol data that cannot price an order (a point of 0, + # a NaN tick size, a volume step of 0). Unlike TERMINAL_ERROR it does not + # clear on a resend, so it has its own kind: a bot must escalate, not retry. + BROKEN_SYMBOL_DATA = "broken_symbol_data" CONNECTION_FAILED = "connection_failed" diff --git a/src/PythonMetaTrader5/domain/symbol.py b/src/PythonMetaTrader5/domain/symbol.py index 901db06..f457dc3 100644 --- a/src/PythonMetaTrader5/domain/symbol.py +++ b/src/PythonMetaTrader5/domain/symbol.py @@ -44,11 +44,12 @@ class SymbolSpec: exchange_execution: bool # Broken terminal data (a point of 0 or inf, a NaN tick size, a volume step - # of 0) is reported as TERMINAL_ERROR: it is the broker's fault, and a bot - # must not file it as a bad signal. It is checked on use rather than refused - # for the whole spec, because closing a position needs only filling_flags - # and must keep working on such a symbol (a constructor invariant was tried - # and dropped for exactly that). Entries call check_tradable() first. + # of 0) is reported as BROKEN_SYMBOL_DATA: it is the broker's fault, so a bot + # must not file it as a bad signal, nor resend as after a TERMINAL_ERROR. + # It is checked on use rather than refused for the whole spec, because + # closing a position needs only filling_flags and must keep working on such + # a symbol (a constructor invariant was tried and dropped for exactly that). + # Entries call check_tradable() first. def check_tradable(self) -> Result[None, TradeError]: problem = self._pricing_problem() or self._volume_problem() @@ -120,7 +121,7 @@ def _volume_problem(self) -> str | None: return None def _data_error(self, problem: str) -> TradeError: - return TradeError(ErrorKind.TERMINAL_ERROR, f"{self.name}: broken symbol data: {problem}") + return TradeError(ErrorKind.BROKEN_SYMBOL_DATA, f"{self.name}: {problem}") def market_filling(self) -> Filling: # FOK first: a webhook bot asking for 1 lot must get 1 lot or nothing. @@ -147,4 +148,11 @@ def _volume_error(self, volume: float, reason: str) -> TradeError: def _usable(value: float) -> bool: - return math.isfinite(value) and value > 0 + # The type check keeps a hand-built spec (point=None, point=True) on the + # Result path instead of raising TypeError from math.isfinite. + return ( + isinstance(value, (int, float)) + and not isinstance(value, bool) + and math.isfinite(value) + and value > 0 + ) diff --git a/tests/unit/test_symbol.py b/tests/unit/test_symbol.py index ae2bd8a..2145226 100644 --- a/tests/unit/test_symbol.py +++ b/tests/unit/test_symbol.py @@ -68,4 +68,4 @@ def test_market_filling_prefers_fill_or_kill(flags: int, expected: Filling) -> N def test_pricing_on_broken_data_is_a_terminal_error_even_when_called_directly() -> None: result = on_grid(eurusd(point=0.0, tick_size=0.0), 1.1) assert isinstance(result, Err) - assert result.error.kind is ErrorKind.TERMINAL_ERROR + assert result.error.kind is ErrorKind.BROKEN_SYMBOL_DATA diff --git a/tests/unit/test_symbol_data.py b/tests/unit/test_symbol_data.py index f94413d..995839c 100644 --- a/tests/unit/test_symbol_data.py +++ b/tests/unit/test_symbol_data.py @@ -37,10 +37,26 @@ def test_a_symbol_without_a_usable_step_prices_nothing( ): assert isinstance(result, Err) # The broker's data is at fault, not the caller's input. - assert result.error.kind is ErrorKind.TERMINAL_ERROR + assert result.error.kind is ErrorKind.BROKEN_SYMBOL_DATA assert terminal.sent == [] +def test_broken_data_is_reported_before_the_callers_volume_is_judged( + trader: Trader, terminal: FakeTerminal +) -> None: + terminal.specs["EURUSD"] = replace(EURUSD, tick_size=math.nan) + result = trader.open_position("EURUSD", "buy", 1000.0) # above volume_max too + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.BROKEN_SYMBOL_DATA + + +def test_a_hand_built_spec_with_a_non_number_is_refused_not_raised() -> None: + spec = replace(EURUSD, point=None, tick_size=0.0) # type: ignore[arg-type] + result = spec.check_tradable() + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.BROKEN_SYMBOL_DATA + + @pytest.mark.parametrize("point", [0.0, math.inf, math.nan]) def test_points_stops_need_a_usable_point_but_prices_do_not( trader: Trader, terminal: FakeTerminal, point: float @@ -49,7 +65,7 @@ def test_points_stops_need_a_usable_point_but_prices_do_not( terminal.specs["EURUSD"] = replace(EURUSD, point=point) refused = trader.open_position("EURUSD", "buy", 0.1, sl=Stop.points(1000)) assert isinstance(refused, Err) - assert refused.error.kind is ErrorKind.TERMINAL_ERROR + assert refused.error.kind is ErrorKind.BROKEN_SYMBOL_DATA assert terminal.sent == [] assert isinstance(trader.open_position("EURUSD", "buy", 0.1, sl=1.09), Ok) @@ -61,7 +77,7 @@ def test_unusable_volume_limits_refuse_every_entry( terminal.specs["EURUSD"] = replace(EURUSD, **broken) result = trader.open_position("EURUSD", "buy", 0.1) assert isinstance(result, Err) - assert result.error.kind is ErrorKind.TERMINAL_ERROR + assert result.error.kind is ErrorKind.BROKEN_SYMBOL_DATA assert terminal.sent == [] @@ -132,3 +148,19 @@ def test_a_points_take_profit_below_zero_is_refused(trader: Trader, terminal: Fa assert isinstance(result, Err) assert result.error.kind is ErrorKind.INVALID_STOPS assert terminal.sent == [] + + +def test_a_points_stop_on_a_limit_needs_a_usable_point( + trader: Trader, terminal: FakeTerminal +) -> None: + terminal.specs["EURUSD"] = replace(EURUSD, point=0.0) + result = trader.place_limit_order("EURUSD", "buy", 0.1, 1.05, sl=Stop.points(100)) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.BROKEN_SYMBOL_DATA + assert terminal.sent == [] + + +def test_volume_checked_directly_on_broken_limits_is_broken_symbol_data() -> None: + result = replace(EURUSD, volume_step=0.0).validate_volume(0.1) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.BROKEN_SYMBOL_DATA From f3f835cc22e190eeff667ad4adbd7595012de51f Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 12:28:57 +0100 Subject: [PATCH 25/28] feat: keep re-exporting the MetaTrader5 namespace for 2.x star imports The owner asked to keep the MT5 functions in the package. The 2.x README itself called `symbol_info("EURUSD")` after `from PythonMetaTrader5 import *`, so scripts written from it would hit NameError after a plain `pip install -U`. - legacy/mt5_namespace.py loads MetaTrader5 when it is installed and lists its public names. __init__ adds them as package attributes and to __all__. Our names win a collision: today only `Tick`, where MT5 has its own tick struct. Without the package (Linux, macOS, CI) nothing is added and the import still works. - time, loguru's logger and pyautogui, which 2.x also leaked, are not restored. Two are no longer dependencies, and a leaked stdlib module is not an API. - ADR 0010 supersedes the "drop the star re-export" part of ADR 0006 and records the remaining cost: new MT5 names enter our namespace, and MetaTrader5 is now imported eagerly. Importing it does not attach to a terminal; only initialize() does. - MIGRATION, CHANGELOG and README now describe the star import as it is. RED: the unit tests failed on the missing module, and the contract star import test failed with KeyError 'symbol_info'. --- CHANGELOG.md | 5 +-- MIGRATION.md | 18 +++++----- README.md | 3 +- docs/adr/0006-legacy-facade.md | 3 +- .../0010-keep-the-metatrader5-re-export.md | 36 +++++++++++++++++++ src/PythonMetaTrader5/__init__.py | 9 +++++ src/PythonMetaTrader5/legacy/mt5_namespace.py | 31 ++++++++++++++++ tests/contract/test_mt5_contract.py | 11 ++++++ tests/unit/test_mt5_namespace.py | 25 +++++++++++++ 9 files changed, 128 insertions(+), 13 deletions(-) create mode 100644 docs/adr/0010-keep-the-metatrader5-re-export.md create mode 100644 src/PythonMetaTrader5/legacy/mt5_namespace.py create mode 100644 tests/unit/test_mt5_namespace.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 0a6e231..8b20b1e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -42,8 +42,9 @@ Complete rewrite. See [MIGRATION.md](MIGRATION.md) for every behaviour change. ### Removed - `pyautogui` Ctrl+E hotkey on retcode 10027. -- The `import *` re-exports of `MetaTrader5`, `time`, loguru's `logger` and - `pyautogui`. +- The `import *` re-exports of `time`, loguru's `logger` and `pyautogui`. The + `MetaTrader5` namespace is still re-exported (ADR 0010); only `Tick` now + means the library's quote model. - The `Broker.password` attribute. ### Safety diff --git a/MIGRATION.md b/MIGRATION.md index e679280..9035aa1 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -62,19 +62,19 @@ upgrading a bot that trades real money. | `GetPositions()` returned raw MT5 `TradePosition` objects | `LegacyPosition` named tuples with every `TradePosition` field in MT5's order; `as_dict=True` returns the same 12 keys as before | No dependency on MT5 internals | | `broker.password` attribute | Removed; credentials are kept in a non-printing object | The password showed up in debug dumps | -## Removed: the `import *` re-exports +## Star import: MetaTrader5 names stay, three others are gone -2.x re-exported the whole `MetaTrader5` namespace plus the modules it used -itself. `from PythonMetaTrader5 import *` therefore also gave you -`symbol_info`, `ORDER_TYPE_BUY` and friends, and `time`, `logger` (loguru) and -`pyautogui`. None of these come through any more. Import them yourself: +`from PythonMetaTrader5 import *` still brings in the `MetaTrader5` +namespace (`symbol_info`, `ORDER_TYPE_BUY`, ...), as in 2.x (ADR 0010). Two +differences: + +- `Tick` is now the library's own quote model, not MT5's tick struct. Use + `MetaTrader5.Tick` if you need the struct. +- `time`, `logger` (loguru) and `pyautogui`, which 2.x also leaked through the + star import, are gone. Import them yourself: ```python import time - -import MetaTrader5 as mt5 - -info = mt5.symbol_info("EURUSD") ``` ## Logging diff --git a/README.md b/README.md index 5470e08..ac1ccd3 100644 --- a/README.md +++ b/README.md @@ -152,7 +152,8 @@ logging configuration, warnings and errors still reach stderr. ## Migrating from 2.x `from PythonMetaTrader5 import Broker` keeps working and emits a -`DeprecationWarning`. Several 2.x behaviours were unsafe and changed: see +`DeprecationWarning`. `from PythonMetaTrader5 import *` still brings in the +`MetaTrader5` functions and constants, as in 2.x. Several 2.x behaviours were unsafe and changed: see [MIGRATION.md](MIGRATION.md). ## Development diff --git a/docs/adr/0006-legacy-facade.md b/docs/adr/0006-legacy-facade.md index cc9a519..eac0426 100644 --- a/docs/adr/0006-legacy-facade.md +++ b/docs/adr/0006-legacy-facade.md @@ -1,6 +1,7 @@ # ADR 0006: Keep a 2.x `Broker` facade; drop the star re-export -- Status: accepted (3.0.0) +- Status: accepted (3.0.0). The star re-export decision is superseded by + [ADR 0010](0010-keep-the-metatrader5-re-export.md). ## Context diff --git a/docs/adr/0010-keep-the-metatrader5-re-export.md b/docs/adr/0010-keep-the-metatrader5-re-export.md new file mode 100644 index 0000000..71a9d13 --- /dev/null +++ b/docs/adr/0010-keep-the-metatrader5-re-export.md @@ -0,0 +1,36 @@ +# ADR 0010: Keep re-exporting the MetaTrader5 namespace + +- Status: accepted (3.0.0). Supersedes the "drop the star re-export" part + of [ADR 0006](0006-legacy-facade.md). + +## Context + +ADR 0006 removed the `from MetaTrader5 import *` that 2.x ran in its +`__init__`. Its reason was that every new MT5 name became part of our public +API without review. But 2.x's own README called `symbol_info("EURUSD")` after +`from PythonMetaTrader5 import *`, so scripts written from that README would +fail with `NameError` after a plain `pip install -U`. The package owner +asked to keep the names. + +## Decision + +`PythonMetaTrader5/__init__.py` re-exports every public name of the +installed `MetaTrader5` module, both as package attributes and in `__all__`, +so `from PythonMetaTrader5 import *` behaves as it did in 2.x. + +- Our own names win a collision. Today the only one is `Tick`: ours is the + quote model, while MT5's is its tick struct. +- Without the package (Linux, macOS, CI) nothing is re-exported, and the + library still imports. +- `time`, loguru's `logger` and `pyautogui`, which 2.x also leaked, are not + restored. The last two are no longer dependencies, and leaking a stdlib + module is not an API. + +## Consequences + +- The ADR 0006 concern still holds: new MT5 releases add names to our + namespace. The cost is bounded because our names win and nothing in the + library uses the re-exported names. +- `import PythonMetaTrader5` now imports `MetaTrader5` eagerly. Importing it + does not start or attach to a terminal; only `initialize()` does. +- `tests/contract` checks the star import against the real package. diff --git a/src/PythonMetaTrader5/__init__.py b/src/PythonMetaTrader5/__init__.py index 61251e8..2729365 100644 --- a/src/PythonMetaTrader5/__init__.py +++ b/src/PythonMetaTrader5/__init__.py @@ -23,6 +23,7 @@ ) from PythonMetaTrader5.domain.orders import Side from PythonMetaTrader5.domain.stops import Stop, StopKind +from PythonMetaTrader5.legacy import mt5_namespace from PythonMetaTrader5.legacy.broker import Broker from PythonMetaTrader5.result import Err, Ok, Result @@ -46,3 +47,11 @@ "Trader", "connect", ] + +# 2.x re-exported the whole MetaTrader5 namespace, and its README relied on it +# (`symbol_info("EURUSD")` after a star import). Kept for those scripts rather +# than breaking them on upgrade (ADR 0010); our own names win a collision. +_reexported = mt5_namespace.public_names(mt5_namespace.load(), taken=set(globals())) +globals().update(_reexported) +__all__ += sorted(_reexported) # noqa: PLE0605 - extended at import time on purpose +del _reexported diff --git a/src/PythonMetaTrader5/legacy/mt5_namespace.py b/src/PythonMetaTrader5/legacy/mt5_namespace.py new file mode 100644 index 0000000..5fc6435 --- /dev/null +++ b/src/PythonMetaTrader5/legacy/mt5_namespace.py @@ -0,0 +1,31 @@ +"""The MetaTrader5 namespace, re-exported for 2.x scripts (ADR 0010). + +2.x ran ``from MetaTrader5 import *`` in its ``__init__``, and its own README +called ``symbol_info("EURUSD")`` after ``from PythonMetaTrader5 import *``. +""" + +from __future__ import annotations + +import importlib +from collections.abc import Collection +from types import ModuleType + + +def load() -> ModuleType | None: + # None, not an error: the package exists only on Windows, and importing this + # library elsewhere (CI, type checking, docs) must keep working. + try: + return importlib.import_module("MetaTrader5") + except ImportError: + return None + + +def public_names(module: ModuleType | None, *, taken: Collection[str]) -> dict[str, object]: + """Public MT5 names that do not collide with ours; ours win (MT5 has a ``Tick`` too).""" + if module is None: + return {} + return { + name: getattr(module, name) + for name in dir(module) + if not name.startswith("_") and name not in taken + } diff --git a/tests/contract/test_mt5_contract.py b/tests/contract/test_mt5_contract.py index 2abd5c7..0702d3b 100644 --- a/tests/contract/test_mt5_contract.py +++ b/tests/contract/test_mt5_contract.py @@ -13,6 +13,7 @@ import pytest +from PythonMetaTrader5.domain.market import Tick from PythonMetaTrader5.legacy.views import LegacyPosition, LegacyReceipt from tests.unit.fake_mt5 import CONSTANTS, FakeMT5, raw_order, raw_position, symbol_info @@ -40,3 +41,13 @@ def test_fake_rows_only_use_fields_the_real_objects_have() -> None: assert set(vars(FakeMT5().send_result)) == set(fields(mt5.OrderSendResult)) - {"request"} assert set(vars(raw_order())) <= set(fields(mt5.TradeOrder)) assert set(vars(symbol_info())) <= set(fields(mt5.SymbolInfo)) + + +def test_the_2x_star_import_still_brings_the_metatrader5_namespace() -> None: + namespace: dict[str, Any] = {} + exec("from PythonMetaTrader5 import *", namespace) # noqa: S102 - the 2.x idiom itself + assert namespace["symbol_info"] is mt5.symbol_info + assert namespace["ORDER_TYPE_BUY"] == mt5.ORDER_TYPE_BUY + # Our names win a collision: MT5 has its own Tick struct. + assert namespace["Tick"] is Tick + assert namespace["Broker"].__module__ == "PythonMetaTrader5.legacy.broker" diff --git a/tests/unit/test_mt5_namespace.py b/tests/unit/test_mt5_namespace.py new file mode 100644 index 0000000..7957ad4 --- /dev/null +++ b/tests/unit/test_mt5_namespace.py @@ -0,0 +1,25 @@ +"""2.x re-exported the MetaTrader5 namespace; scripts call symbol_info() through it.""" + +from __future__ import annotations + +import sys +from types import SimpleNamespace + +import pytest + +from PythonMetaTrader5.legacy import mt5_namespace + + +def test_public_names_are_taken_and_ours_win_a_collision() -> None: + module = SimpleNamespace(symbol_info=print, ORDER_TYPE_BUY=0, Tick=object, _private=1) + names = mt5_namespace.public_names(module, taken={"Tick"}) # type: ignore[arg-type] + assert names == {"symbol_info": print, "ORDER_TYPE_BUY": 0} + + +def test_nothing_is_re_exported_without_the_package() -> None: + assert mt5_namespace.public_names(None, taken=set()) == {} + + +def test_load_gives_none_where_the_package_is_missing(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setitem(sys.modules, "MetaTrader5", None) + assert mt5_namespace.load() is None From 05e3c359e13807e0725d1b6237654cbe1e7d62d9 Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 12:33:26 +0100 Subject: [PATCH 26/28] refactor: re-export the MetaTrader5 namespace lazily, under the session lock /code-review high on f3f835c found that the first draft was too shallow: - A broken MT5 install (DLL load failure, missing numpy) was hidden. Any ImportError meant "re-export nothing", and the user later got a NameError on symbol_info, far from the cause. Now only "MetaTrader5 is not installed" means no names. Any other import failure raises where an MT5 name is used, and the adapter reports it as "installed but cannot be imported" instead of "not installed". - The eager import made every `import PythonMetaTrader5`, even of domain types only, pay for MT5 and numpy (65 of 87 ms) and fail with them. The package now has a PEP 562 __getattr__: MT5 names resolve on first use, and a star import gets __all__ through the same hook. Our own names stay plain attributes and win (Tick). They are re-exported with `X as X` because __all__ is computed. - Re-exported functions bypassed the adapter's lock, so a direct last_error() could interleave with the adapter's order_send and make a lost order look "never sent". They are now wrapped to hold the same lock. adapters/mt5_session.py holds that lock and the one MetaTrader5 import site, shared by the adapter and the re-export, so the two can no longer diverge. - The wiring is unit-tested with the fake module: the star import, the lock, missing vs broken installs, dir(), no eager import, and that time/logger/pyautogui stay absent. The contract test checks the real package. - ADR 0010 records the lazy design and the typing cost: __getattr__ returns Any, so typos on the package root no longer fail type checks. ADR 0006's title marks the superseded part. The CHANGELOG moves the namespace from Removed to Changed. ADR 0009, architecture.md, MIGRATION and README mention the lock. Removed names (mt5_namespace.load, mt5_terminal._SESSION, _reexported): grep over src tests docs *.md finds no remaining use. RED: the new unit tests failed on the missing mt5_session module. --- CHANGELOG.md | 8 +- MIGRATION.md | 5 +- README.md | 5 +- docs/adr/0006-legacy-facade.md | 2 +- docs/adr/0009-one-lock-per-process.md | 6 +- .../0010-keep-the-metatrader5-re-export.md | 46 ++++++---- docs/architecture.md | 4 +- src/PythonMetaTrader5/__init__.py | 65 ++++++++------ src/PythonMetaTrader5/adapters/mt5_session.py | 47 ++++++++++ .../adapters/mt5_terminal.py | 33 ++----- src/PythonMetaTrader5/legacy/mt5_namespace.py | 44 ++++++---- tests/contract/test_mt5_contract.py | 2 +- tests/unit/test_mt5_namespace.py | 87 ++++++++++++++++--- 13 files changed, 247 insertions(+), 107 deletions(-) create mode 100644 src/PythonMetaTrader5/adapters/mt5_session.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 8b20b1e..1df1083 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -32,6 +32,10 @@ Complete rewrite. See [MIGRATION.md](MIGRATION.md) for every behaviour change. - `Broker` is a deprecated facade over `Trader` with the 2.x method names. It returns `LegacyPosition` / `LegacyReceipt` named tuples with the fields and field order of MT5's `TradePosition` / `OrderSendResult`. +- The `MetaTrader5` namespace is still re-exported for `import *` and attribute + access, but lazily and under the session lock (ADR 0010). `Tick` now means + the library's quote model, and importing the library no longer imports + `MetaTrader5`. - `Position` carries every `TradePosition` field (`swap`, `identifier`, ...); `TradeReceipt` gains `retcode_external`. - Bounded retries (requotes only) instead of endless loops. @@ -42,9 +46,7 @@ Complete rewrite. See [MIGRATION.md](MIGRATION.md) for every behaviour change. ### Removed - `pyautogui` Ctrl+E hotkey on retcode 10027. -- The `import *` re-exports of `time`, loguru's `logger` and `pyautogui`. The - `MetaTrader5` namespace is still re-exported (ADR 0010); only `Tick` now - means the library's quote model. +- The `import *` re-exports of `time`, loguru's `logger` and `pyautogui`. - The `Broker.password` attribute. ### Safety diff --git a/MIGRATION.md b/MIGRATION.md index 9035aa1..517cbdc 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -65,8 +65,9 @@ upgrading a bot that trades real money. ## Star import: MetaTrader5 names stay, three others are gone `from PythonMetaTrader5 import *` still brings in the `MetaTrader5` -namespace (`symbol_info`, `ORDER_TYPE_BUY`, ...), as in 2.x (ADR 0010). Two -differences: +namespace (`symbol_info`, `ORDER_TYPE_BUY`, ...), as in 2.x (ADR 0010). The +functions now run under the library's session lock, so they cannot interleave +with a `Trader` call in another thread. Two differences: - `Tick` is now the library's own quote model, not MT5's tick struct. Use `MetaTrader5.Tick` if you need the struct. diff --git a/README.md b/README.md index ac1ccd3..d10f27b 100644 --- a/README.md +++ b/README.md @@ -35,8 +35,9 @@ Built for bots (webhook executors, signal followers) where a trading call must > first. Run one process per account. > > Thread-safe within the library: every terminal call holds one process-wide -> lock, so a threaded webhook server can share a `Trader`. Calls you make to -> the `MetaTrader5` module directly bypass that lock. +> lock, so a threaded webhook server can share a `Trader`. The MT5 functions +> re-exported through `PythonMetaTrader5` hold it too. Calls you make to the +> `MetaTrader5` module directly bypass it. > > Requires Windows with a MetaTrader 5 terminal installed (the official > `MetaTrader5` package is Windows-only). Enable **Algo Trading** in the terminal. diff --git a/docs/adr/0006-legacy-facade.md b/docs/adr/0006-legacy-facade.md index eac0426..ee27d53 100644 --- a/docs/adr/0006-legacy-facade.md +++ b/docs/adr/0006-legacy-facade.md @@ -1,4 +1,4 @@ -# ADR 0006: Keep a 2.x `Broker` facade; drop the star re-export +# ADR 0006: Keep a 2.x `Broker` facade (star re-export: superseded by ADR 0010) - Status: accepted (3.0.0). The star re-export decision is superseded by [ADR 0010](0010-keep-the-metatrader5-re-export.md). diff --git a/docs/adr/0009-one-lock-per-process.md b/docs/adr/0009-one-lock-per-process.md index 3da3d9d..2d07218 100644 --- a/docs/adr/0009-one-lock-per-process.md +++ b/docs/adr/0009-one-lock-per-process.md @@ -27,5 +27,7 @@ separate locks would not exclude each other. session per process anyway, so no parallelism is lost. - A slow call (a login waiting for `timeout_ms`) delays the other threads for that long. -- Calls that user code makes to the `MetaTrader5` module directly are outside - the lock. The README says so. +- Functions re-exported through `PythonMetaTrader5` (ADR 0010) run under the + lock too. The lock lives in `adapters/mt5_session.py`. Calls that user code + makes to the `MetaTrader5` module directly are outside it, and the README + says so. diff --git a/docs/adr/0010-keep-the-metatrader5-re-export.md b/docs/adr/0010-keep-the-metatrader5-re-export.md index 71a9d13..fa1eb10 100644 --- a/docs/adr/0010-keep-the-metatrader5-re-export.md +++ b/docs/adr/0010-keep-the-metatrader5-re-export.md @@ -1,4 +1,4 @@ -# ADR 0010: Keep re-exporting the MetaTrader5 namespace +# ADR 0010: Keep re-exporting the MetaTrader5 namespace, lazily - Status: accepted (3.0.0). Supersedes the "drop the star re-export" part of [ADR 0006](0006-legacy-facade.md). @@ -14,23 +14,39 @@ asked to keep the names. ## Decision -`PythonMetaTrader5/__init__.py` re-exports every public name of the -installed `MetaTrader5` module, both as package attributes and in `__all__`, -so `from PythonMetaTrader5 import *` behaves as it did in 2.x. - -- Our own names win a collision. Today the only one is `Tick`: ours is the - quote model, while MT5's is its tick struct. -- Without the package (Linux, macOS, CI) nothing is re-exported, and the - library still imports. +The package defines a module `__getattr__` (PEP 562). Our own names are +regular module attributes and always win, e.g. `Tick` (ours is the quote +model, MT5's is its tick struct). Any other public name is looked up in +`MetaTrader5` on first use. A star import asks for `__all__` through the same +hook and gets our names plus MT5's. + +- **Lazy.** We rejected the first draft, which ran `from MetaTrader5 import *` + eagerly in `__init__`. It made every `import PythonMetaTrader5` (even of + the pure domain types) pay for MT5 and numpy, and fail with them: a numpy + ABI mismatch would have broken the import itself. +- **Missing vs broken.** "Not installed" (the normal case outside Windows) + means MT5 contributes no names. An installed package that fails to import + (a missing DLL or dependency) raises where an MT5 name is used, with the + real cause, instead of turning into a `NameError` later. + `adapters/mt5_session.import_metatrader5` is the one import site, shared + with the adapter. +- **Locked.** Re-exported functions run under the adapter's process-wide + session lock (ADR 0009). Otherwise a direct `last_error()` could run + between the adapter's `order_send` and its own `last_error()` read, and a + lost order would be reported as "never sent". - `time`, loguru's `logger` and `pyautogui`, which 2.x also leaked, are not restored. The last two are no longer dependencies, and leaking a stdlib module is not an API. ## Consequences -- The ADR 0006 concern still holds: new MT5 releases add names to our - namespace. The cost is bounded because our names win and nothing in the - library uses the re-exported names. -- `import PythonMetaTrader5` now imports `MetaTrader5` eagerly. Importing it - does not start or attach to a terminal; only `initialize()` does. -- `tests/contract` checks the star import against the real package. +- New MT5 releases add names to our namespace, as ADR 0006 warned. The cost is + bounded: our names win, and nothing in the library uses the re-exports. +- An MT5 name that equals one of our submodules (`result`, `connection`, ...) + resolves to the submodule. None does today. +- For type checkers, the module `__getattr__` returns `Any`, so + `from PythonMetaTrader5 import symbol_info` type-checks, but so does a typo + like `PythonMetaTrader5.Trder`. Our own names keep their real types. +- Re-exported functions are wrappers: `__wrapped__` is the MT5 original. +- `tests/unit/test_mt5_namespace.py` covers the wiring with the fake module, + and `tests/contract` covers the real one. diff --git a/docs/architecture.md b/docs/architecture.md index 990793e..11eab54 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -44,7 +44,9 @@ volume checks) is plain functions and methods on domain objects, not ports. `last_error()` in the `MetaTrader5` package is process-global, so the adapter holds one module-level lock around every terminal call and the error read that -explains it ([ADR 0009](adr/0009-one-lock-per-process.md)). +explains it ([ADR 0009](adr/0009-one-lock-per-process.md)). The lock and the +single `MetaTrader5` import live in `adapters/mt5_session.py`, shared with the +lazy 2.x namespace re-export ([ADR 0010](adr/0010-keep-the-metatrader5-re-export.md)). ## Errors diff --git a/src/PythonMetaTrader5/__init__.py b/src/PythonMetaTrader5/__init__.py index 2729365..b2f31dd 100644 --- a/src/PythonMetaTrader5/__init__.py +++ b/src/PythonMetaTrader5/__init__.py @@ -9,25 +9,30 @@ print(error) """ -from PythonMetaTrader5.application.batch import BatchFailure -from PythonMetaTrader5.application.execution import RetryPolicy -from PythonMetaTrader5.application.trader import Trader -from PythonMetaTrader5.connection import connect -from PythonMetaTrader5.domain.errors import ErrorKind, TradeError -from PythonMetaTrader5.domain.market import ( - PendingKind, - PendingOrder, - Position, - Tick, - TradeReceipt, -) -from PythonMetaTrader5.domain.orders import Side -from PythonMetaTrader5.domain.stops import Stop, StopKind -from PythonMetaTrader5.legacy import mt5_namespace -from PythonMetaTrader5.legacy.broker import Broker -from PythonMetaTrader5.result import Err, Ok, Result +from typing import Any + +# `X as X`: explicit re-exports, because __all__ is computed (see __getattr__). +from PythonMetaTrader5.application.batch import BatchFailure as BatchFailure +from PythonMetaTrader5.application.execution import RetryPolicy as RetryPolicy +from PythonMetaTrader5.application.trader import Trader as Trader +from PythonMetaTrader5.connection import connect as connect +from PythonMetaTrader5.domain.errors import ErrorKind as ErrorKind +from PythonMetaTrader5.domain.errors import TradeError as TradeError +from PythonMetaTrader5.domain.market import PendingKind as PendingKind +from PythonMetaTrader5.domain.market import PendingOrder as PendingOrder +from PythonMetaTrader5.domain.market import Position as Position +from PythonMetaTrader5.domain.market import Tick as Tick +from PythonMetaTrader5.domain.market import TradeReceipt as TradeReceipt +from PythonMetaTrader5.domain.orders import Side as Side +from PythonMetaTrader5.domain.stops import Stop as Stop +from PythonMetaTrader5.domain.stops import StopKind as StopKind +from PythonMetaTrader5.legacy import mt5_namespace as _mt5_namespace +from PythonMetaTrader5.legacy.broker import Broker as Broker +from PythonMetaTrader5.result import Err as Err +from PythonMetaTrader5.result import Ok as Ok +from PythonMetaTrader5.result import Result as Result -__all__ = [ +_OWN_NAMES = ( "BatchFailure", "Broker", "Err", @@ -46,12 +51,18 @@ "TradeReceipt", "Trader", "connect", -] - -# 2.x re-exported the whole MetaTrader5 namespace, and its README relied on it -# (`symbol_info("EURUSD")` after a star import). Kept for those scripts rather -# than breaking them on upgrade (ADR 0010); our own names win a collision. -_reexported = mt5_namespace.public_names(mt5_namespace.load(), taken=set(globals())) -globals().update(_reexported) -__all__ += sorted(_reexported) # noqa: PLE0605 - extended at import time on purpose -del _reexported +) + + +def __getattr__(name: str) -> Any: + # 2.x re-exported the whole MetaTrader5 namespace and its README relied on it + # (`symbol_info("EURUSD")` after a star import), so those names resolve here, + # lazily (ADR 0010). A star import asks for __all__ through this hook too. + # Names defined in this module always win, e.g. our Tick over MT5's struct. + if name == "__all__": + return [*_OWN_NAMES, *_mt5_namespace.public_names(taken=set(globals()))] + return _mt5_namespace.resolve(name, taken=set(globals())) + + +def __dir__() -> list[str]: + return sorted({*globals(), *__getattr__("__all__")}) diff --git a/src/PythonMetaTrader5/adapters/mt5_session.py b/src/PythonMetaTrader5/adapters/mt5_session.py new file mode 100644 index 0000000..e38ab46 --- /dev/null +++ b/src/PythonMetaTrader5/adapters/mt5_session.py @@ -0,0 +1,47 @@ +"""The one MetaTrader5 session of a process: how it is imported and locked. + +Shared by the adapter and the 2.x namespace re-export, so both import the +package the same way and every call through either holds the same lock. +""" + +from __future__ import annotations + +import functools +import importlib +import threading +from collections.abc import Callable +from types import ModuleType +from typing import ParamSpec, TypeVar + +# last_error() is process-global, so a call and the error read that explains it +# must not interleave with another thread's call. Module-level, not per adapter: +# connect() builds a new adapter each time, and every adapter and re-exported +# function in a process talks to the one MT5 session (ADR 0009). +SESSION = threading.RLock() +_P = ParamSpec("_P") +_R = TypeVar("_R") + + +def serialized(function: Callable[_P, _R]) -> Callable[_P, _R]: + @functools.wraps(function) + def locked(*args: _P.args, **kwargs: _P.kwargs) -> _R: + with SESSION: + return function(*args, **kwargs) + + return locked + + +def import_metatrader5() -> ModuleType | None: + """The MetaTrader5 module, or None when it is not installed. + + Only "not installed" becomes None: it is the normal case outside Windows. A + package that is installed but fails to import (a missing DLL, a numpy ABI + mismatch) raises, so the real cause is reported where the names are used, + instead of surfacing later as a NameError on symbol_info. + """ + try: + return importlib.import_module("MetaTrader5") + except ModuleNotFoundError as error: + if error.name == "MetaTrader5": + return None + raise diff --git a/src/PythonMetaTrader5/adapters/mt5_terminal.py b/src/PythonMetaTrader5/adapters/mt5_terminal.py index cc46d06..badb243 100644 --- a/src/PythonMetaTrader5/adapters/mt5_terminal.py +++ b/src/PythonMetaTrader5/adapters/mt5_terminal.py @@ -6,14 +6,11 @@ from __future__ import annotations -import functools -import importlib import math -import threading -from collections.abc import Callable -from typing import Any, ParamSpec, TypeVar +from typing import Any from PythonMetaTrader5.adapters import mt5_mapping +from PythonMetaTrader5.adapters.mt5_session import import_metatrader5, serialized from PythonMetaTrader5.application.ports import Credentials from PythonMetaTrader5.domain.errors import ErrorKind, TradeError from PythonMetaTrader5.domain.market import PendingOrder, Position, Tick, TradeReceipt @@ -35,23 +32,8 @@ "RES_E_INTERNAL_FAIL_CONNECT", ) -# last_error() is process-global, so a call and the error read that explains it -# must not interleave with another thread's call. The lock is module-level, not -# per adapter: connect() builds a new adapter each time, and two Traders in one -# process share the one MT5 session. Direct MetaTrader5 calls made by user code -# are outside this lock. -_SESSION = threading.RLock() -_P = ParamSpec("_P") -_R = TypeVar("_R") - - -def _serialized(method: Callable[_P, _R]) -> Callable[_P, _R]: - @functools.wraps(method) - def locked(*args: _P.args, **kwargs: _P.kwargs) -> _R: - with _SESSION: - return method(*args, **kwargs) - - return locked +# Every public method holds the process-wide session lock (ADR 0009). +_serialized = serialized class MetaTrader5Terminal: @@ -86,8 +68,11 @@ def __init__(self, mt5: Any) -> None: @classmethod def load(cls) -> Result[MetaTrader5Terminal, TradeError]: try: - module = importlib.import_module("MetaTrader5") - except ImportError: + module = import_metatrader5() + except ImportError as error: + message = f"the MetaTrader5 package is installed but cannot be imported: {error}" + return Err(TradeError(ErrorKind.CONNECTION_FAILED, message)) + if module is None: return Err( TradeError( ErrorKind.CONNECTION_FAILED, diff --git a/src/PythonMetaTrader5/legacy/mt5_namespace.py b/src/PythonMetaTrader5/legacy/mt5_namespace.py index 5fc6435..5198057 100644 --- a/src/PythonMetaTrader5/legacy/mt5_namespace.py +++ b/src/PythonMetaTrader5/legacy/mt5_namespace.py @@ -1,31 +1,37 @@ -"""The MetaTrader5 namespace, re-exported for 2.x scripts (ADR 0010). +"""The MetaTrader5 namespace, re-exported lazily for 2.x scripts (ADR 0010). 2.x ran ``from MetaTrader5 import *`` in its ``__init__``, and its own README called ``symbol_info("EURUSD")`` after ``from PythonMetaTrader5 import *``. +The package ``__getattr__`` (PEP 562) delegates here, so MetaTrader5 is +imported only when one of its names is first used: importing the library, or +only its domain types, never depends on the MT5 wheel. """ from __future__ import annotations -import importlib from collections.abc import Collection -from types import ModuleType +from PythonMetaTrader5.adapters.mt5_session import import_metatrader5, serialized -def load() -> ModuleType | None: - # None, not an error: the package exists only on Windows, and importing this - # library elsewhere (CI, type checking, docs) must keep working. - try: - return importlib.import_module("MetaTrader5") - except ImportError: - return None - -def public_names(module: ModuleType | None, *, taken: Collection[str]) -> dict[str, object]: - """Public MT5 names that do not collide with ours; ours win (MT5 has a ``Tick`` too).""" +def public_names(*, taken: Collection[str]) -> list[str]: + module = import_metatrader5() if module is None: - return {} - return { - name: getattr(module, name) - for name in dir(module) - if not name.startswith("_") and name not in taken - } + return [] + return sorted(n for n in dir(module) if not n.startswith("_") and n not in taken) + + +def resolve(name: str, *, taken: Collection[str]) -> object: + """One MT5 name; functions are wrapped to hold the adapter's session lock. + + Without the lock a direct ``last_error()`` from a 2.x-style script could run + between the adapter's ``order_send`` and its own ``last_error()`` read, and + a lost order would be reported as "never sent" (ADR 0009). + """ + module = None if name.startswith("_") or name in taken else import_metatrader5() + if module is None or not hasattr(module, name): + raise AttributeError(f"module 'PythonMetaTrader5' has no attribute {name!r}") + value = getattr(module, name) + if callable(value) and not isinstance(value, type): + return serialized(value) + return value diff --git a/tests/contract/test_mt5_contract.py b/tests/contract/test_mt5_contract.py index 0702d3b..9a07643 100644 --- a/tests/contract/test_mt5_contract.py +++ b/tests/contract/test_mt5_contract.py @@ -46,7 +46,7 @@ def test_fake_rows_only_use_fields_the_real_objects_have() -> None: def test_the_2x_star_import_still_brings_the_metatrader5_namespace() -> None: namespace: dict[str, Any] = {} exec("from PythonMetaTrader5 import *", namespace) # noqa: S102 - the 2.x idiom itself - assert namespace["symbol_info"] is mt5.symbol_info + assert namespace["symbol_info"].__wrapped__ is mt5.symbol_info # locked wrapper assert namespace["ORDER_TYPE_BUY"] == mt5.ORDER_TYPE_BUY # Our names win a collision: MT5 has its own Tick struct. assert namespace["Tick"] is Tick diff --git a/tests/unit/test_mt5_namespace.py b/tests/unit/test_mt5_namespace.py index 7957ad4..30b227b 100644 --- a/tests/unit/test_mt5_namespace.py +++ b/tests/unit/test_mt5_namespace.py @@ -2,24 +2,91 @@ from __future__ import annotations +import subprocess import sys -from types import SimpleNamespace +from typing import Any import pytest -from PythonMetaTrader5.legacy import mt5_namespace +import PythonMetaTrader5 +from PythonMetaTrader5.adapters import mt5_session +from PythonMetaTrader5.adapters.mt5_terminal import MetaTrader5Terminal +from PythonMetaTrader5.domain.errors import ErrorKind +from PythonMetaTrader5.domain.market import Tick +from PythonMetaTrader5.result import Err +from .fake_mt5 import FakeMT5 -def test_public_names_are_taken_and_ours_win_a_collision() -> None: - module = SimpleNamespace(symbol_info=print, ORDER_TYPE_BUY=0, Tick=object, _private=1) - names = mt5_namespace.public_names(module, taken={"Tick"}) # type: ignore[arg-type] - assert names == {"symbol_info": print, "ORDER_TYPE_BUY": 0} +def star_import() -> dict[str, Any]: + namespace: dict[str, Any] = {} + exec("from PythonMetaTrader5 import *", namespace) # noqa: S102 - the 2.x idiom itself + return namespace -def test_nothing_is_re_exported_without_the_package() -> None: - assert mt5_namespace.public_names(None, taken=set()) == {} +def test_the_2x_star_import_brings_mt5_names_and_ours_win(no_real_terminal: FakeMT5) -> None: + names = star_import() + assert names["ORDER_TYPE_BUY"] == 0 + assert names["Tick"] is Tick # MT5 has its own Tick struct; ours wins + assert names["Broker"] is PythonMetaTrader5.Broker + names["symbol_select"]("EURUSD", True) + assert no_real_terminal.calls[-1] == ("symbol_select", ("EURUSD", True), {}) + for leaked_by_2x in ("time", "logger", "pyautogui"): + assert leaked_by_2x not in names -def test_load_gives_none_where_the_package_is_missing(monkeypatch: pytest.MonkeyPatch) -> None: + +def test_re_exported_functions_run_under_the_adapters_session_lock( + no_real_terminal: FakeMT5, +) -> None: + held: list[bool] = [] + no_real_terminal.last_error = lambda: held.append(mt5_session.SESSION._is_owned()) or (1, "") # type: ignore[attr-defined, method-assign, func-returns-value] + PythonMetaTrader5.last_error() + assert held == [True] + + +def test_without_the_package_only_our_names_exist(monkeypatch: pytest.MonkeyPatch) -> None: monkeypatch.setitem(sys.modules, "MetaTrader5", None) - assert mt5_namespace.load() is None + names = star_import() + assert "Broker" in names + assert "symbol_info" not in names + with pytest.raises(AttributeError, match="symbol_info"): + _ = PythonMetaTrader5.symbol_info + + +def test_a_broken_install_is_reported_not_hidden(monkeypatch: pytest.MonkeyPatch) -> None: + def broken(name: str) -> None: + raise ImportError("DLL load failed while importing _core") + + monkeypatch.setattr(mt5_session.importlib, "import_module", broken) + with pytest.raises(ImportError, match="DLL load failed"): + _ = PythonMetaTrader5.symbol_info + loaded = MetaTrader5Terminal.load() + assert isinstance(loaded, Err) + assert loaded.error.kind is ErrorKind.CONNECTION_FAILED + assert "DLL load failed" in loaded.error.message + + +def test_importing_the_library_does_not_import_metatrader5() -> None: + # The re-export is lazy: pure-domain users and tooling never pay for or + # depend on the MetaTrader5 import. + probe = "import sys, PythonMetaTrader5; print('MetaTrader5' in sys.modules)" + out = subprocess.run( # noqa: S603 - fixed arguments, our own interpreter + [sys.executable, "-c", probe], capture_output=True, text=True, check=True + ) + assert out.stdout.strip() == "False" + + +def test_dir_lists_our_names_and_the_mt5_names(no_real_terminal: FakeMT5) -> None: + listed = dir(PythonMetaTrader5) + assert {"Broker", "connect", "symbol_info", "ORDER_TYPE_BUY"} <= set(listed) + + +def test_a_missing_dependency_of_metatrader5_is_reported_not_hidden( + monkeypatch: pytest.MonkeyPatch, +) -> None: + def numpy_missing(name: str) -> None: + raise ModuleNotFoundError("No module named 'numpy'", name="numpy") + + monkeypatch.setattr(mt5_session.importlib, "import_module", numpy_missing) + with pytest.raises(ModuleNotFoundError, match="numpy"): + _ = PythonMetaTrader5.symbol_info From d046e6a266ac26fe021fc3266e88135b4558abfa Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 12:37:10 +0100 Subject: [PATCH 27/28] fix: a broken MetaTrader5 install keeps the star import working and says why /code-review high on 05e3c35. Fixed: the findings that raise out of a Result boundary or regress this branch. - On a broken install, `from PythonMetaTrader5 import *` raised ImportError, even for scripts that only use connect(). hasattr(), getattr(.., default) and dir() raised as well, which breaks IDEs and pydoc. Now the star import keeps our names and emits a RuntimeWarning with the cause. An MT5 name raises AttributeError chained to the ImportError, so hasattr is False and the cause is kept. connect() returns Err(CONNECTION_FAILED). - An AttributeError or ValueError raised while MetaTrader5 imported (numpy ABI mismatch) escaped. The AttributeError read as "no __all__" and silently emptied the star import; others escaped connect() as raw exceptions. import_metatrader5 now turns every failure except "not installed" into ImportError with the cause, and the adapter already maps ImportError to Err. - Dead `taken` parameter dropped: a module __getattr__ only runs on misses. The collision filter for __all__ stays in __init__, where it takes effect. The `_serialized` alias and its comment are gone; methods use `@serialized`. - MIGRATION, README and ADR 0010 no longer claim that re-exported calls "cannot interleave". The lock covers one call, not a script's own order_send + last_error pair. - Tests patch mt5_session's importlib reference instead of the stdlib module, and cover ImportError, ModuleNotFoundError of a dependency, AttributeError and ValueError. Debt (ADR 0010): resolved names and the "not installed" outcome are not cached, so each access re-resolves. This affects performance and identity, not correctness. RED: 4 cases in test_mt5_namespace.py failed before the change. --- MIGRATION.md | 6 ++- README.md | 3 +- .../0010-keep-the-metatrader5-re-export.md | 15 +++++-- src/PythonMetaTrader5/__init__.py | 5 ++- src/PythonMetaTrader5/adapters/mt5_session.py | 11 +++-- .../adapters/mt5_terminal.py | 17 ++++---- src/PythonMetaTrader5/legacy/mt5_namespace.py | 31 ++++++++++---- tests/unit/test_mt5_namespace.py | 40 +++++++++++-------- 8 files changed, 83 insertions(+), 45 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 517cbdc..6c1b027 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -66,8 +66,10 @@ upgrading a bot that trades real money. `from PythonMetaTrader5 import *` still brings in the `MetaTrader5` namespace (`symbol_info`, `ORDER_TYPE_BUY`, ...), as in 2.x (ADR 0010). The -functions now run under the library's session lock, so they cannot interleave -with a `Trader` call in another thread. Two differences: +functions now run under the library's session lock, so a single call cannot +land between a `Trader`'s `order_send` and its error read. A sequence of your +own calls (`order_send` then `last_error`) is not atomic, just as in 2.x. Two +differences: - `Tick` is now the library's own quote model, not MT5's tick struct. Use `MetaTrader5.Tick` if you need the struct. diff --git a/README.md b/README.md index d10f27b..9fe4941 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,8 @@ Built for bots (webhook executors, signal followers) where a trading call must > > Thread-safe within the library: every terminal call holds one process-wide > lock, so a threaded webhook server can share a `Trader`. The MT5 functions -> re-exported through `PythonMetaTrader5` hold it too. Calls you make to the +> re-exported through `PythonMetaTrader5` hold it for each single call (a pair +> such as `order_send` + `last_error` is not atomic). Calls you make to the > `MetaTrader5` module directly bypass it. > > Requires Windows with a MetaTrader 5 terminal installed (the official diff --git a/docs/adr/0010-keep-the-metatrader5-re-export.md b/docs/adr/0010-keep-the-metatrader5-re-export.md index fa1eb10..c93effa 100644 --- a/docs/adr/0010-keep-the-metatrader5-re-export.md +++ b/docs/adr/0010-keep-the-metatrader5-re-export.md @@ -26,8 +26,12 @@ hook and gets our names plus MT5's. ABI mismatch would have broken the import itself. - **Missing vs broken.** "Not installed" (the normal case outside Windows) means MT5 contributes no names. An installed package that fails to import - (a missing DLL or dependency) raises where an MT5 name is used, with the - real cause, instead of turning into a `NameError` later. + (a missing DLL or dependency, a numpy ABI mismatch raising ValueError or + AttributeError) is turned into an `ImportError` with the cause. The star + import then keeps our names and emits a `RuntimeWarning`, an MT5 name raises + `AttributeError` carrying the cause (so `hasattr` and IDEs keep working), + and `connect()` returns `Err(CONNECTION_FAILED)`. A raised `ImportError` + would crash the star import even for scripts that only use `connect`. `adapters/mt5_session.import_metatrader5` is the one import site, shared with the adapter. - **Locked.** Re-exported functions run under the adapter's process-wide @@ -47,6 +51,11 @@ hook and gets our names plus MT5's. - For type checkers, the module `__getattr__` returns `Any`, so `from PythonMetaTrader5 import symbol_info` type-checks, but so does a typo like `PythonMetaTrader5.Trder`. Our own names keep their real types. -- Re-exported functions are wrappers: `__wrapped__` is the MT5 original. +- Re-exported functions are wrappers: `__wrapped__` is the MT5 original. They + are resolved on every access (no cache), so `pkg.symbol_info is + pkg.symbol_info` is False, and each access costs a few microseconds. The + lock covers one call, not a sequence of a script's own calls. +- Known debt: neither resolved names nor the "not installed" outcome are + cached, so tools probing many attributes repeat the import lookup. - `tests/unit/test_mt5_namespace.py` covers the wiring with the fake module, and `tests/contract` covers the real one. diff --git a/src/PythonMetaTrader5/__init__.py b/src/PythonMetaTrader5/__init__.py index b2f31dd..f133f6b 100644 --- a/src/PythonMetaTrader5/__init__.py +++ b/src/PythonMetaTrader5/__init__.py @@ -60,8 +60,9 @@ def __getattr__(name: str) -> Any: # lazily (ADR 0010). A star import asks for __all__ through this hook too. # Names defined in this module always win, e.g. our Tick over MT5's struct. if name == "__all__": - return [*_OWN_NAMES, *_mt5_namespace.public_names(taken=set(globals()))] - return _mt5_namespace.resolve(name, taken=set(globals())) + mt5_names = _mt5_namespace.public_names() + return [*_OWN_NAMES, *(n for n in mt5_names if n not in globals())] + return _mt5_namespace.resolve(name) def __dir__() -> list[str]: diff --git a/src/PythonMetaTrader5/adapters/mt5_session.py b/src/PythonMetaTrader5/adapters/mt5_session.py index e38ab46..f513c54 100644 --- a/src/PythonMetaTrader5/adapters/mt5_session.py +++ b/src/PythonMetaTrader5/adapters/mt5_session.py @@ -35,13 +35,16 @@ def import_metatrader5() -> ModuleType | None: """The MetaTrader5 module, or None when it is not installed. Only "not installed" becomes None: it is the normal case outside Windows. A - package that is installed but fails to import (a missing DLL, a numpy ABI - mismatch) raises, so the real cause is reported where the names are used, - instead of surfacing later as a NameError on symbol_info. + package that is installed but fails to import raises ImportError, whatever + it raised itself: a numpy ABI mismatch can surface as ValueError or + AttributeError, and an AttributeError leaking out of the package + __getattr__ would read as "no such name" and silently empty the star import. """ try: return importlib.import_module("MetaTrader5") except ModuleNotFoundError as error: if error.name == "MetaTrader5": return None - raise + raise ImportError(f"MetaTrader5 is installed but cannot be imported: {error}") from error + except Exception as error: + raise ImportError(f"MetaTrader5 is installed but cannot be imported: {error}") from error diff --git a/src/PythonMetaTrader5/adapters/mt5_terminal.py b/src/PythonMetaTrader5/adapters/mt5_terminal.py index badb243..55615b9 100644 --- a/src/PythonMetaTrader5/adapters/mt5_terminal.py +++ b/src/PythonMetaTrader5/adapters/mt5_terminal.py @@ -32,9 +32,6 @@ "RES_E_INTERNAL_FAIL_CONNECT", ) -# Every public method holds the process-wide session lock (ADR 0009). -_serialized = serialized - class MetaTrader5Terminal: def __init__(self, mt5: Any) -> None: @@ -81,7 +78,7 @@ def load(cls) -> Result[MetaTrader5Terminal, TradeError]: ) return Ok(cls(module)) - @_serialized + @serialized def connect(self, credentials: Credentials) -> Result[None, TradeError]: args = (credentials.path,) if credentials.path else () if self._mt5.initialize( @@ -106,11 +103,11 @@ def connect(self, credentials: Credentials) -> Result[None, TradeError]: ) ) - @_serialized + @serialized def shutdown(self) -> None: self._mt5.shutdown() - @_serialized + @serialized def symbol(self, name: str) -> Result[SymbolSpec, TradeError]: info = self._mt5.symbol_info(name) if info is None: @@ -137,7 +134,7 @@ def symbol(self, name: str) -> Result[SymbolSpec, TradeError]: ) ) - @_serialized + @serialized def tick(self, name: str) -> Result[Tick, TradeError]: tick = self._mt5.symbol_info_tick(name) # A zero side means no quote yet; trading at price 0 must never be attempted. @@ -146,7 +143,7 @@ def tick(self, name: str) -> Result[Tick, TradeError]: return Err(TradeError(ErrorKind.NO_PRICE, f"no quote for {name!r}")) return Ok(Tick(bid=float(tick.bid), ask=float(tick.ask))) - @_serialized + @serialized def send(self, request: OrderRequest | CancelRequest) -> Result[TradeReceipt, TradeError]: payload = self._payload(request) result = self._mt5.order_send(payload) @@ -154,7 +151,7 @@ def send(self, request: OrderRequest | CancelRequest) -> Result[TradeReceipt, Tr return Err(self._send_failure()) return Ok(mt5_mapping.receipt(result)) - @_serialized + @serialized def positions( self, *, symbol: str | None = None, ticket: int | None = None ) -> Result[list[Position], TradeError]: @@ -170,7 +167,7 @@ def positions( # MT5 ignores `symbol` once `ticket` is given; the port promises both apply. return Ok([p for p in found if symbol is None or p.symbol == symbol]) - @_serialized + @serialized def pending_orders( self, *, symbol: str | None = None ) -> Result[list[PendingOrder], TradeError]: diff --git a/src/PythonMetaTrader5/legacy/mt5_namespace.py b/src/PythonMetaTrader5/legacy/mt5_namespace.py index 5198057..d941b20 100644 --- a/src/PythonMetaTrader5/legacy/mt5_namespace.py +++ b/src/PythonMetaTrader5/legacy/mt5_namespace.py @@ -9,29 +9,46 @@ from __future__ import annotations -from collections.abc import Collection +import warnings +from types import ModuleType from PythonMetaTrader5.adapters.mt5_session import import_metatrader5, serialized -def public_names(*, taken: Collection[str]) -> list[str]: - module = import_metatrader5() +def public_names() -> list[str]: + module = _module_or_warn() if module is None: return [] - return sorted(n for n in dir(module) if not n.startswith("_") and n not in taken) + return sorted(n for n in dir(module) if not n.startswith("_")) -def resolve(name: str, *, taken: Collection[str]) -> object: +def resolve(name: str) -> object: """One MT5 name; functions are wrapped to hold the adapter's session lock. Without the lock a direct ``last_error()`` from a 2.x-style script could run between the adapter's ``order_send`` and its own ``last_error()`` read, and - a lost order would be reported as "never sent" (ADR 0009). + a lost order would be reported as "never sent" (ADR 0009). Only names not + defined by the package reach this: a module __getattr__ runs on misses only. """ - module = None if name.startswith("_") or name in taken else import_metatrader5() + try: + module = None if name.startswith("_") else import_metatrader5() + except ImportError as error: + # AttributeError, not ImportError: hasattr(), getattr(.., default) and + # IDE tooling must keep working on a broken install; the cause is kept. + raise AttributeError(f"PythonMetaTrader5 has no attribute {name!r}: {error}") from error if module is None or not hasattr(module, name): raise AttributeError(f"module 'PythonMetaTrader5' has no attribute {name!r}") value = getattr(module, name) if callable(value) and not isinstance(value, type): return serialized(value) return value + + +def _module_or_warn() -> ModuleType | None: + try: + return import_metatrader5() + except ImportError as error: + # A star import of a broken install keeps our own names (connect() then + # reports the failure as Err) and says loudly why the MT5 names are gone. + warnings.warn(f"{error}; its names are not re-exported", RuntimeWarning, stacklevel=3) + return None diff --git a/tests/unit/test_mt5_namespace.py b/tests/unit/test_mt5_namespace.py index 30b227b..3cf0e38 100644 --- a/tests/unit/test_mt5_namespace.py +++ b/tests/unit/test_mt5_namespace.py @@ -4,6 +4,7 @@ import subprocess import sys +from types import SimpleNamespace from typing import Any import pytest @@ -53,17 +54,35 @@ def test_without_the_package_only_our_names_exist(monkeypatch: pytest.MonkeyPatc _ = PythonMetaTrader5.symbol_info -def test_a_broken_install_is_reported_not_hidden(monkeypatch: pytest.MonkeyPatch) -> None: +@pytest.mark.parametrize( + "failure", + [ + ImportError("DLL load failed while importing _core"), + ModuleNotFoundError("No module named 'numpy'", name="numpy"), + AttributeError("module 'numpy' has no attribute '_ARRAY_API'"), + ValueError("numpy.dtype size changed"), + ], +) +def test_a_broken_install_is_reported_without_breaking_imports_or_tools( + monkeypatch: pytest.MonkeyPatch, failure: Exception +) -> None: def broken(name: str) -> None: - raise ImportError("DLL load failed while importing _core") + raise failure - monkeypatch.setattr(mt5_session.importlib, "import_module", broken) - with pytest.raises(ImportError, match="DLL load failed"): + # Replaces the importlib reference inside mt5_session only, not the stdlib. + monkeypatch.setattr(mt5_session, "importlib", SimpleNamespace(import_module=broken)) + with pytest.warns(RuntimeWarning, match="cannot be imported"): + names = star_import() + assert "connect" in names # a script using only connect() still imports + assert "symbol_info" not in names + assert not hasattr(PythonMetaTrader5, "symbol_info") + with pytest.raises(AttributeError, match="cannot be imported") as raised: _ = PythonMetaTrader5.symbol_info + assert isinstance(raised.value.__cause__, ImportError) loaded = MetaTrader5Terminal.load() assert isinstance(loaded, Err) assert loaded.error.kind is ErrorKind.CONNECTION_FAILED - assert "DLL load failed" in loaded.error.message + assert str(failure) in loaded.error.message def test_importing_the_library_does_not_import_metatrader5() -> None: @@ -79,14 +98,3 @@ def test_importing_the_library_does_not_import_metatrader5() -> None: def test_dir_lists_our_names_and_the_mt5_names(no_real_terminal: FakeMT5) -> None: listed = dir(PythonMetaTrader5) assert {"Broker", "connect", "symbol_info", "ORDER_TYPE_BUY"} <= set(listed) - - -def test_a_missing_dependency_of_metatrader5_is_reported_not_hidden( - monkeypatch: pytest.MonkeyPatch, -) -> None: - def numpy_missing(name: str) -> None: - raise ModuleNotFoundError("No module named 'numpy'", name="numpy") - - monkeypatch.setattr(mt5_session.importlib, "import_module", numpy_missing) - with pytest.raises(ModuleNotFoundError, match="numpy"): - _ = PythonMetaTrader5.symbol_info From ceb11027325bdef9db30d5cec483168d9d8051c9 Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 12:39:38 +0100 Subject: [PATCH 28/28] fix: single error prefix, warning points at the user's import, docs caveat Follow-up to the /code-review high findings on d046e6a. These are small, mechanical fixes and get no separate review round. The PR says so. - connect() on a broken install said "installed but cannot be imported" twice. load() now passes import_metatrader5's message through, and the test pins the exact text. - The RuntimeWarning used stacklevel 3 and so pointed at the library's __getattr__. It now uses 4 and names the user's import line. - import_metatrader5 has one except clause and one raise instead of two identical ones. - CHANGELOG gets the per-call lock caveat that README, MIGRATION and ADR 0010 already carry. - ADR 0010 lists the remaining debt: no caching of the import outcome, and on a broken install hasattr/getattr(..., None) do not warn while star import and dir() do. --- CHANGELOG.md | 3 ++- docs/adr/0010-keep-the-metatrader5-re-export.md | 12 ++++++++++-- src/PythonMetaTrader5/adapters/mt5_session.py | 6 ++---- src/PythonMetaTrader5/adapters/mt5_terminal.py | 4 ++-- src/PythonMetaTrader5/legacy/mt5_namespace.py | 4 +++- tests/unit/test_mt5_namespace.py | 2 +- 6 files changed, 20 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1df1083..df2ca96 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -33,7 +33,8 @@ Complete rewrite. See [MIGRATION.md](MIGRATION.md) for every behaviour change. returns `LegacyPosition` / `LegacyReceipt` named tuples with the fields and field order of MT5's `TradePosition` / `OrderSendResult`. - The `MetaTrader5` namespace is still re-exported for `import *` and attribute - access, but lazily and under the session lock (ADR 0010). `Tick` now means + access, but lazily, and each re-exported call holds the session lock (a + sequence of calls is not atomic; ADR 0010). `Tick` now means the library's quote model, and importing the library no longer imports `MetaTrader5`. - `Position` carries every `TradePosition` field (`swap`, `identifier`, ...); diff --git a/docs/adr/0010-keep-the-metatrader5-re-export.md b/docs/adr/0010-keep-the-metatrader5-re-export.md index c93effa..95996b7 100644 --- a/docs/adr/0010-keep-the-metatrader5-re-export.md +++ b/docs/adr/0010-keep-the-metatrader5-re-export.md @@ -55,7 +55,15 @@ hook and gets our names plus MT5's. are resolved on every access (no cache), so `pkg.symbol_info is pkg.symbol_info` is False, and each access costs a few microseconds. The lock covers one call, not a sequence of a script's own calls. -- Known debt: neither resolved names nor the "not installed" outcome are - cached, so tools probing many attributes repeat the import lookup. +- Known debt: + - Neither resolved names nor the import outcome (missing or broken) are + cached. Tools that probe many attributes repeat the import lookup, and on + a broken install they re-run the failing import each time. + - On a broken install, `hasattr` / `getattr(pkg, name, None)` give + False / None without a warning; the cause is only in `__cause__` of the + AttributeError. Star imports and `dir()` warn instead, and they raise + under `-W error`. A 2.x script that uses an MT5 name after the star + import still ends in a NameError; the RuntimeWarning beforehand names the + cause. - `tests/unit/test_mt5_namespace.py` covers the wiring with the fake module, and `tests/contract` covers the real one. diff --git a/src/PythonMetaTrader5/adapters/mt5_session.py b/src/PythonMetaTrader5/adapters/mt5_session.py index f513c54..bf5099b 100644 --- a/src/PythonMetaTrader5/adapters/mt5_session.py +++ b/src/PythonMetaTrader5/adapters/mt5_session.py @@ -42,9 +42,7 @@ def import_metatrader5() -> ModuleType | None: """ try: return importlib.import_module("MetaTrader5") - except ModuleNotFoundError as error: - if error.name == "MetaTrader5": - return None - raise ImportError(f"MetaTrader5 is installed but cannot be imported: {error}") from error except Exception as error: + if isinstance(error, ModuleNotFoundError) and error.name == "MetaTrader5": + return None raise ImportError(f"MetaTrader5 is installed but cannot be imported: {error}") from error diff --git a/src/PythonMetaTrader5/adapters/mt5_terminal.py b/src/PythonMetaTrader5/adapters/mt5_terminal.py index 55615b9..d2ee095 100644 --- a/src/PythonMetaTrader5/adapters/mt5_terminal.py +++ b/src/PythonMetaTrader5/adapters/mt5_terminal.py @@ -67,8 +67,8 @@ def load(cls) -> Result[MetaTrader5Terminal, TradeError]: try: module = import_metatrader5() except ImportError as error: - message = f"the MetaTrader5 package is installed but cannot be imported: {error}" - return Err(TradeError(ErrorKind.CONNECTION_FAILED, message)) + # import_metatrader5 already says "installed but cannot be imported". + return Err(TradeError(ErrorKind.CONNECTION_FAILED, str(error))) if module is None: return Err( TradeError( diff --git a/src/PythonMetaTrader5/legacy/mt5_namespace.py b/src/PythonMetaTrader5/legacy/mt5_namespace.py index d941b20..7b5bef1 100644 --- a/src/PythonMetaTrader5/legacy/mt5_namespace.py +++ b/src/PythonMetaTrader5/legacy/mt5_namespace.py @@ -50,5 +50,7 @@ def _module_or_warn() -> ModuleType | None: except ImportError as error: # A star import of a broken install keeps our own names (connect() then # reports the failure as Err) and says loudly why the MT5 names are gone. - warnings.warn(f"{error}; its names are not re-exported", RuntimeWarning, stacklevel=3) + # stacklevel 4: past this helper, public_names and the package + # __getattr__, so the warning names the user's import line. + warnings.warn(f"{error}; its names are not re-exported", RuntimeWarning, stacklevel=4) return None diff --git a/tests/unit/test_mt5_namespace.py b/tests/unit/test_mt5_namespace.py index 3cf0e38..a2225cb 100644 --- a/tests/unit/test_mt5_namespace.py +++ b/tests/unit/test_mt5_namespace.py @@ -82,7 +82,7 @@ def broken(name: str) -> None: loaded = MetaTrader5Terminal.load() assert isinstance(loaded, Err) assert loaded.error.kind is ErrorKind.CONNECTION_FAILED - assert str(failure) in loaded.error.message + assert loaded.error.message == f"MetaTrader5 is installed but cannot be imported: {failure}" def test_importing_the_library_does_not_import_metatrader5() -> None: