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

PythonMetaTrader5/domain/inputs.py

@@ -0,0 +1,106 @@
+"""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
+
+from dataclasses import replace
+from enum import Enum
+from numbers import Integral
+from typing import Final
+
+from PythonMetaTrader5.domain.amounts import positive_float
+from PythonMetaTrader5.domain.errors import ErrorKind, TradeError
+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]:
+    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 or isinstance(value, Stop):
+        return Ok(value)  # a Stop validated itself when it was built
+    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]:
+    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)
+
+
+class AnyMagic(Enum):
+    """The type of ``ANY_MAGIC``."""
+
+    ANY = "any"
+
+
+# A named value, not None: close-all and cancel-all default to the trader's own
+# magic, and a None read from a missing config key must not widen them to the
+# whole account (ADR 0011).
+ANY_MAGIC: Final = AnyMagic.ANY
+# MT5 stores magic as a ulong; a larger value would overflow in order_send.
+_MAX_MAGIC: Final = 2**64 - 1
+
+
+def magic_filter(magic: object) -> Result[int | AnyMagic | None, TradeError]:
+    # "42" or True would match no position and report an empty success with
+    # everything still open. 0 is valid: it is what manual trades carry.
+    if magic is None or magic is ANY_MAGIC:
+        return Ok(magic)
+    if (
+        isinstance(magic, bool)
+        or not isinstance(magic, Integral)
+        or not 0 <= int(magic) <= _MAX_MAGIC
+    ):
+        return Err(
+            TradeError(
+                ErrorKind.INVALID_ARGUMENT,
+                f"magic must be an integer from 0 to 2**64-1 or ANY_MAGIC, got {magic!r}",
+            )
+        )
+    return Ok(int(magic))
+
+
+def own_magic(magic: object) -> Result[int, TradeError]:
+    """The magic a trader stamps on its orders and closes by default."""
+    checked = magic_filter(magic)
+    # None or ANY_MAGIC here would make the own-magic default mean "every magic",
+    # and a missing config key would close the whole account (ADR 0011). One
+    # message for every refusal: magic_filter's would suggest ANY_MAGIC.
+    if isinstance(checked, Err) or not isinstance(checked.value, int):
+        return Err(
+            TradeError(
+                ErrorKind.INVALID_ARGUMENT,
+                f"the trader's own magic must be an integer from 0 to 2**64-1, got {magic!r}",
+            )
+        )
+    return Ok(checked.value)

PythonMetaTrader5/domain/market.py

@@ -0,0 +1,91 @@
+"""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
+    # 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)
+        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
+    retcode_external: int

PythonMetaTrader5/domain/orders.py

@@ -0,0 +1,64 @@
+"""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])
+
+
+# Measured with order_check, not taken from the docs: MetaTrader5 5.0.6231
+# accepts 29 UTF-16 code units and refuses 30 with [-2] Invalid "comment"
+# argument before sending. The documented 31 would let 30-31 through to a
+# TERMINAL_ERROR that hides the cause, and trimming would change what the user
+# asked to store. tests/integration re-measures it when the package changes.
+MAX_COMMENT_LENGTH = 29
+
+
+def validate_comment(comment: object) -> Result[str, TradeError]:
+    if comment is None:
+        return Ok("")
+    # `comment or ""` would store 0 or False as an empty comment without a word.
+    if not isinstance(comment, str):
+        return Err(TradeError(ErrorKind.INVALID_ARGUMENT, f"comment must be text, not {comment!r}"))
+    # The package counts UTF-16 units, not len(): "\U0001f680" * 15 is refused.
+    # surrogatepass: the package accepts a lone surrogate (measured), so it is
+    # one unit here, not a UnicodeEncodeError.
+    units = len(comment.encode("utf-16-le", "surrogatepass")) // 2
+    if units > MAX_COMMENT_LENGTH:
+        return Err(
+            TradeError(
+                ErrorKind.INVALID_ARGUMENT,
+                f"comment is {units} UTF-16 units (characters outside the BMP, such as "
+                f"most emoji, count as 2; combined emoji more); "
+                f"the MetaTrader5 package accepts at most {MAX_COMMENT_LENGTH}",
+            )
+        )
+    return Ok(comment)

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

PythonMetaTrader5/domain/retcodes.py

@@ -0,0 +1,81 @@
+"""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.
+PLACED = 10008
+DONE = 10009
+DONE_PARTIAL = 10010
+_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
+# automatic retry would open a second position.
+_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"),
+    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; 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"),
+    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"),
+    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)

PythonMetaTrader5/domain/stops.py

@@ -0,0 +1,85 @@
+"""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.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):
+    PRICE = "price"
+    POINTS = "points"
+
+
+@dataclass(frozen=True, slots=True)
+class Stop:
+    value: float
+    kind: StopKind
+
+    def __post_init__(self) -> None:
+        # The invariant lives here, so every Stop is valid wherever it is built.
+        # 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.
+        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:
+        return cls(price, StopKind.PRICE)
+
+    @classmethod
+    def points(cls, distance: float) -> Stop:
+        return cls(distance, StopKind.POINTS)
+
+    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
+    ) -> Result[float, TradeError]:
+        return self._resolve(side.sign, reference, spec, "tp")
+
+    def _resolve(
+        self, direction: int, reference: float, spec: SymbolSpec, what: str
+    ) -> Result[float, TradeError]:
+        # 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:
+            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)
+
+
+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)
+    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)

PythonMetaTrader5/domain/symbol.py

@@ -0,0 +1,158 @@
+"""Instrument specification and the rules that depend only on it."""
+
+from __future__ import annotations
+
+import math
+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
+    # 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
+
+    # Broken terminal data (a point of 0 or inf, a NaN tick size, a volume step
+    # 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()
+        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.
+
+        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".
+        """
+        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 = 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]:
+        # 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):
+            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]:
+        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
+        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))
+
+    @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.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.
+        # 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 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,
+            f"{self.name}: volume {volume} is {reason} "
+            f"[{self.volume_min}, {self.volume_max}] step {self.volume_step}",
+        )
+
+
+def _usable(value: float) -> bool:
+    # 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
+    )

PythonMetaTrader5/legacy/__init__.py

@@ -0,0 +1 @@
+"""Deprecated 2.x API kept so existing scripts run unchanged on 3.x."""

PythonMetaTrader5/legacy/arguments.py

@@ -0,0 +1,52 @@
+"""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, StopKind
+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":
+            stop_kind = StopKind.PRICE
+        case "offset":
+            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)
+    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", parsed.error)
+        return Err(parsed.error.message)
+    return Ok(parsed.value)
+
+
+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