PythonMetaTrader5 2.3.2__py3-none-any.whl → 3.0.0__py3-none-any.whl

PythonMetaTrader5/adapters/mt5_mapping.py

@@ -0,0 +1,92 @@
+"""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),
+        retcode_external=int(result.retcode_external),
+    )
+
+
+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),
+        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),
+    )
+
+
+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

PythonMetaTrader5/adapters/mt5_session.py

@@ -0,0 +1,48 @@
+"""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 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 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

PythonMetaTrader5/adapters/mt5_terminal.py

@@ -0,0 +1,224 @@
+"""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 math
+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
+from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest
+from PythonMetaTrader5.domain.symbol import Filling, SymbolSpec
+from PythonMetaTrader5.result import Err, Ok, Result
+
+# 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_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:
+    def __init__(self, mt5: Any) -> None:
+        # `Any`: the MetaTrader5 package ships no type information.
+        self._mt5 = 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()
+            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,
+        }
+        # 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
+        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
+
+    @classmethod
+    def load(cls) -> Result[MetaTrader5Terminal, TradeError]:
+        try:
+            module = import_metatrader5()
+        except ImportError as error:
+            # import_metatrader5 already says "installed but cannot be imported".
+            return Err(TradeError(ErrorKind.CONNECTION_FAILED, str(error)))
+        if module is None:
+            return Err(
+                TradeError(
+                    ErrorKind.CONNECTION_FAILED,
+                    "the MetaTrader5 package is not installed (it is available on Windows only)",
+                )
+            )
+        return Ok(cls(module))
+
+    @serialized
+    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)
+        error = self._last_error()
+        # 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,
+                f"login {credentials.login}@{credentials.server} failed: {error}",
+            )
+        )
+
+    @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:
+            return Err(TradeError(ErrorKind.SYMBOL_NOT_FOUND, f"unknown symbol {name!r}"))
+        # 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,
+                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.
+        # 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)))
+
+    @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(mt5_mapping.receipt(result))
+
+    @serialized
+    def positions(
+        self, *, symbol: str | None = None, ticket: int | None = None
+    ) -> Result[list[Position], TradeError]:
+        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
+        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]:
+        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
+        return Ok(mt5_mapping.pending_orders(raw.value, self._pending_by_type))
+
+    # ------------------------------------------------------------------ helpers
+
+    def _payload(self, request: OrderRequest | CancelRequest) -> dict[str, Any]:
+        if isinstance(request, CancelRequest):
+            return {"action": self._remove, "order": request.order}
+        payload: dict[str, Any] = {
+            "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)],
+            "price": request.price,
+            "deviation": request.deviation,
+            "magic": request.magic,
+            "comment": request.comment,
+            "type_filling": self._fillings[request.filling],
+            "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})
+        return payload
+
+    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 == self._ok:
+            return Ok(())
+        return Err(TradeError(ErrorKind.TERMINAL_ERROR, f"{call} failed: {self._last_error()}"))
+
+    def _send_failure(self) -> TradeError:
+        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: {text}")
+
+    def _last_error(self) -> str:
+        return self._error()[1]
+
+    def _error(self) -> tuple[int, str]:
+        code, message = self._mt5.last_error()
+        return code, f"[{code}] {message}"

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)

PythonMetaTrader5/application/__init__.py

@@ -0,0 +1 @@
+"""Use cases and the ports they need from the outside world."""

PythonMetaTrader5/application/batch.py

@@ -0,0 +1,60 @@
+"""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.inputs import ANY_MAGIC, AnyMagic
+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 | AnyMagic | None) -> list[_T]:
+    if magic is None or magic is ANY_MAGIC:
+        return items
+    return [item for item in items if item.magic == magic]

PythonMetaTrader5/application/entries.py

@@ -0,0 +1,163 @@
+"""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, StopKind
+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
+    # The caller's price on the symbol's tick grid; None means "use the quote".
+    price: float | None
+
+    def request(
+        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 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,
+                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.value,
+                tp=tp.value,
+                pending=pending,
+            )
+        )
+
+
+def validate_entry(
+    terminal: Terminal,
+    symbol: str,
+    side: Side | str,
+    volume: float,
+    *,
+    comment: str | None,
+    sl: StopInput,
+    tp: StopInput,
+    price: object = None,
+    price_required: bool = False,
+) -> Result[Entry, TradeError]:
+    # 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")
+    if isinstance(amount, Err):
+        return amount
+    spec = _tradable_spec(terminal, 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, level = values.value
+    on_grid = _quote_free_levels(spec.value, level, stop_loss, take_profit)
+    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 _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.
+    # 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
+    return Ok(None if level is None else level.value)
+
+
+def _caller_values(
+    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
+    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
+    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))