pmt4api 1.0.0__py3-none-any.whl

pmt4api/_trading.py

@@ -0,0 +1,384 @@
+"""Order entry: market and pending orders, modify, close (also partial and close-by), cancel; synchronous, with a
+request id and progress events, and awaitable.
+
+Nothing here is ever retried or resent. If the server does not confirm within the trade timeout the call raises
+``RequestTimeout`` and the order MAY have been accepted: look at ``orders()`` before sending again.
+"""
+from __future__ import annotations
+
+import asyncio
+import functools
+from datetime import datetime, timedelta
+from typing import Any, Dict, Optional, Union
+
+from ._base import _Base
+from ._util import finite, placed_type as _placed, to_core_time, translated
+from .errors import InvalidRequestError, ServerError
+from .models import Order
+
+Expiry = Union[None, str, datetime, timedelta]
+
+_PENDING = {"buy_limit": "BuyLimit", "sell_limit": "SellLimit", "buy_stop": "BuyStop", "sell_stop": "SellStop"}
+
+#: The longest comment the wire carries (32 bytes, the last being the terminator).
+MAX_COMMENT = 31
+
+_NO_MAGIC = ("the MT4 core accepts a magic number but does not transmit it, so an order cannot be tagged with one "
+             "(its position would come back with magic 0 and a strategy that filters by magic would lose it). Tag "
+             "orders with `comment` instead; Order.magic is still read back from orders that carry one.")
+
+
+class _TradingMixin(_Base):
+    # ---- helpers -----------------------------------------------------------------------------------------------
+
+    def _open_order(self, ticket: int) -> Any:
+        o = self._api.GetOpenedOrder(int(ticket))
+        if o is None:
+            raise InvalidRequestError("no open order or position with ticket %d" % int(ticket))
+        return o
+
+    def _open_position(self, ticket: int) -> Any:
+        o = self._open_order(ticket)
+        if str(o.Type) not in ("Buy", "Sell"):
+            raise InvalidRequestError("ticket %d is a pending order (%s), not a position: use cancel()"
+                                      % (int(ticket), o.Type))
+        return o
+
+    def _open_pending(self, ticket: int) -> Any:
+        o = self._open_order(ticket)
+        if str(o.Type) in ("Buy", "Sell"):
+            raise InvalidRequestError("ticket %d is an open position, not a pending order: use close()" % int(ticket))
+        return o
+
+    @staticmethod
+    def _centilots(lots: float, name: str = "lots") -> float:
+        """``lots`` checked against what the wire can carry: a positive multiple of 0.01 (the core would round
+        anything finer to a different volume, or to zero)."""
+        v = finite(lots, name, positive=True)
+        cents = round(v * 100.0)
+        if cents > 2147483647:
+            raise ValueError("%s %r does not fit the wire (at most 21474836.47 lots)" % (name, lots))
+        if cents < 1 or abs(v * 100.0 - cents) > 1e-6:
+            raise ValueError("%s must be a positive multiple of 0.01 (MT4 carries volume in hundredths of a lot), "
+                             "not %r" % (name, lots))
+        return v
+
+    def _check_comment(self, comment: Optional[str]) -> None:
+        if comment is None:
+            return
+        if len(comment) > MAX_COMMENT:
+            raise ValueError("comment is %d characters; the MT4 wire carries at most %d" % (len(comment), MAX_COMMENT))
+        if not comment.isascii():
+            raise ValueError("comment must be ASCII: orders are read back through an ASCII-only parser, so any other "
+                             "character would come back as '?' and the comment could not be used to find the order")
+        try:
+            comment.encode(self._comment_encoding)
+        except UnicodeEncodeError as exc:
+            raise ValueError("comment cannot be encoded as %s (the client's comment_encoding): %s"
+                             % (self._comment_encoding, exc)) from exc
+
+    @staticmethod
+    def _check_magic(magic: int) -> None:
+        if magic:
+            raise InvalidRequestError("magic=%r: %s" % (magic, _NO_MAGIC))
+
+    def _expiry(self, value: Expiry) -> Any:
+        """A pending order's expiration as the core's ``DateTime`` (``None``: good till cancelled)."""
+        if value is None:
+            return None
+        if isinstance(value, str):
+            if value.strip().lower() == "gtc":
+                import System  # noqa: PLC0415
+                return System.DateTime.MinValue          # good till cancelled
+            raise ValueError("expiration must be 'gtc', a datetime (server time, or timezone-aware) or a timedelta")
+        if isinstance(value, timedelta):
+            base = self.server_time
+            if base is None:
+                raise InvalidRequestError("not connected: the server clock is unknown")
+            return to_core_time(base + value)
+        if isinstance(value, datetime):
+            return to_core_time(self._server_naive(value))
+        raise ValueError("expiration must be 'gtc', a datetime (server time, or timezone-aware) or a timedelta from now")
+
+    def _market_price(self, symbol: str, is_buy: bool) -> float:
+        """The side's current price. May wait up to the client's ``quote_timeout`` for the symbol's first quote;
+        :class:`NoQuoteError` (nothing was sent) when none arrives."""
+        q = self._get_quote(symbol, int(self._api.GetQuoteTimeoutMs))
+        return float(q.Ask) if is_buy else float(q.Bid)
+
+    def _send_args(self, symbol: str, kind: str, lots: float, price: Optional[float], sl: float, tp: float,
+                   slippage: int, comment: Optional[str], magic: int, expiration: Expiry,
+                   placed_type: Optional[str]):
+        self._check_magic(magic)
+        symbol = self._canon(symbol)
+        lots = self._centilots(lots)
+        sl = finite(sl, "sl", non_negative=True)
+        tp = finite(tp, "tp", non_negative=True)
+        if int(slippage) < 0:
+            raise ValueError("slippage must not be negative")
+        self._check_comment(comment)
+        is_pending = kind in _PENDING.values()
+        if price is None:
+            if is_pending:
+                raise ValueError("a pending order needs its price")
+            price = self._market_price(symbol, kind == "Buy")
+        else:
+            price = finite(price, "price", positive=True)
+        positional = (symbol, getattr(self._core.OrderType, kind), lots, price)
+        named: Dict[str, Any] = {"slippage": int(slippage), "stoploss": sl, "takeprofit": tp}
+        if comment is not None:
+            named["comment"] = comment
+        exp = self._expiry(expiration)
+        if exp is not None:
+            named["expiration"] = exp
+        pt = _placed(self._core.PlacedType, placed_type)
+        if pt is not None:
+            named["placedType"] = pt
+        return positional, named
+
+    @staticmethod
+    def _pending_kind(kind: str) -> str:
+        key = str(kind).strip().lower()
+        if key not in _PENDING:
+            raise ValueError("kind must be one of %s" % ", ".join(_PENDING))
+        return _PENDING[key]
+
+    def _confirmed(self, result: Any) -> Order:
+        if result is None:
+            raise ServerError("the server did not return the order; check orders() before sending again")
+        return Order._from_core(result)
+
+    def _close_args(self, ticket: int, lots: Optional[float], price: Optional[float], slippage: int):
+        o = self._open_position(ticket)
+        amount = float(o.Lots) if lots is None else self._centilots(lots)
+        if amount > float(o.Lots) + 1e-9:
+            raise ValueError("lots must be between 0.01 and the position's %g" % float(o.Lots))
+        if int(slippage) < 0:
+            raise ValueError("slippage must not be negative")
+        if price is None:
+            price = self._market_price(str(o.Symbol), str(o.Type) == "Sell")   # a buy closes at the bid
+        else:
+            price = finite(price, "price", positive=True)
+        return o, amount, price
+
+    def _modify_args(self, ticket: int, sl: Optional[float], tp: Optional[float], price: Optional[float],
+                     expiration: Expiry):
+        if sl is None and tp is None and price is None and expiration is None:
+            raise ValueError("nothing to change")
+        o = self._open_order(ticket)
+        pending = str(o.Type) not in ("Buy", "Sell")
+        if price is not None and not pending:
+            raise ValueError("the open price of a position cannot be changed; only a pending order's can")
+        if expiration is not None and not pending:
+            raise ValueError("a position has no expiration; only a pending order does")
+        new_sl = finite(sl, "sl", non_negative=True) if sl is not None else float(o.StopLoss)
+        new_tp = finite(tp, "tp", non_negative=True) if tp is not None else float(o.TakeProfit)
+        new_price = finite(price, "price", positive=True) if price is not None else float(o.OpenPrice)
+        # an omitted expiration would otherwise become "good till cancelled": keep the one the order has
+        exp = self._expiry(expiration) if expiration is not None else (o.ExpirationTime if pending else None)
+        args = (int(o.Ticket), str(o.Symbol), o.Type, float(o.Lots), new_price, new_sl, new_tp)
+        return args, exp
+
+    # ---- synchronous -------------------------------------------------------------------------------------------
+
+    @translated
+    def buy(self, symbol: str, lots: float, *, price: Optional[float] = None, slippage: int = 0, sl: float = 0.0,
+            tp: float = 0.0, comment: Optional[str] = None, magic: int = 0,
+            placed_type: Optional[str] = None) -> Order:
+        """Buy at market. ``price`` defaults to the current ask (an instant-execution symbol fills at it within
+        ``slippage`` points; a market-execution symbol ignores it). ``sl`` / ``tp`` are prices (0 = none); ``lots`` is
+        a multiple of 0.01. ``comment`` (at most 31 characters) is how to tag an order: the core does not transmit a
+        magic number, so ``magic`` other than 0 raises :class:`InvalidRequestError` rather than being ignored.
+        ``placed_type`` is ``manual``, ``expert``, ``dealer`` ... (default: the client's)."""
+        self._require_connected()
+        pos, named = self._send_args(symbol, "Buy", lots, price, sl, tp, slippage, comment, magic, None, placed_type)
+        return self._confirmed(self._api.OrderSend(*pos, **named))
+
+    @translated
+    def sell(self, symbol: str, lots: float, *, price: Optional[float] = None, slippage: int = 0, sl: float = 0.0,
+             tp: float = 0.0, comment: Optional[str] = None, magic: int = 0,
+             placed_type: Optional[str] = None) -> Order:
+        """Sell at market (``price`` defaults to the current bid); see :meth:`buy`."""
+        self._require_connected()
+        pos, named = self._send_args(symbol, "Sell", lots, price, sl, tp, slippage, comment, magic, None, placed_type)
+        return self._confirmed(self._api.OrderSend(*pos, **named))
+
+    @translated
+    def place_order(self, symbol: str, kind: str, lots: float, price: float, *, sl: float = 0.0, tp: float = 0.0,
+                    expiration: Expiry = None, slippage: int = 0, comment: Optional[str] = None, magic: int = 0,
+                    placed_type: Optional[str] = None) -> Order:
+        """Place a pending order. ``kind`` is one of ``buy_limit sell_limit buy_stop sell_stop``. ``expiration`` is
+        ``None`` or ``"gtc"`` (good till cancelled), a ``datetime`` (server time, or timezone-aware) or a
+        ``timedelta`` from now."""
+        self._require_connected()
+        pos, named = self._send_args(symbol, self._pending_kind(kind), lots, price, sl, tp, slippage, comment, magic,
+                                     expiration, placed_type)
+        return self._confirmed(self._api.OrderSend(*pos, **named))
+
+    @translated
+    def modify(self, ticket: int, *, sl: Optional[float] = None, tp: Optional[float] = None,
+               price: Optional[float] = None, expiration: Expiry = None) -> Order:
+        """Change a position's stop-loss / take-profit, or a pending order's price / stops / expiration. Anything
+        left as ``None`` keeps its current value (a pending order's expiration included; ``expiration="gtc"`` clears
+        it). Returns the order as the server now holds it."""
+        self._require_connected()
+        args, exp = self._modify_args(ticket, sl, tp, price, expiration)
+        ticket_, symbol, kind, lots, new_price, new_sl, new_tp = args
+        if exp is not None:
+            result = self._api.OrderModify(ticket_, symbol, kind, lots, new_price, new_sl, new_tp, exp)
+        else:
+            import System  # noqa: PLC0415
+            result = self._api.OrderModify(ticket_, symbol, kind, lots, new_price, new_sl, new_tp,
+                                           System.DateTime.MinValue)
+        return self._confirmed(result)
+
+    @translated
+    def close(self, ticket: int, lots: Optional[float] = None, *, price: Optional[float] = None,
+              slippage: int = 0) -> Order:
+        """Close a position at market, completely or (with ``lots``) in part; ``price`` defaults to the current
+        bid (buy) / ask (sell). Returns the closing record. After a partial close the remainder may carry a new
+        ticket: read :meth:`positions`."""
+        self._require_connected()
+        o, amount, px = self._close_args(ticket, lots, price, slippage)
+        return self._confirmed(self._api.OrderClose(str(o.Symbol), int(o.Ticket), amount, px, int(slippage)))
+
+    @translated
+    def cancel(self, ticket: int) -> None:
+        """Delete a pending order."""
+        self._require_connected()
+        o = self._open_pending(ticket)
+        self._api.OrderCancel(int(o.Ticket), o.Type, str(o.Symbol), float(o.Lots), float(o.OpenPrice))
+
+    @translated
+    def close_by(self, ticket: int, opposite_ticket: int) -> None:
+        """Close a position against an opposite position of the same symbol (hedged accounts); the result arrives as
+        order updates. Both must be open positions of the same symbol and opposite sides."""
+        self._require_connected()
+        a = self._open_position(ticket)
+        b = self._open_position(opposite_ticket)
+        if str(a.Symbol).lower() != str(b.Symbol).lower() or str(a.Type) == str(b.Type):
+            raise InvalidRequestError("close_by needs two opposite positions of the same symbol (%s %s / %s %s)"
+                                      % (a.Symbol, a.Type, b.Symbol, b.Type))
+        self._api.OrderCloseBy(str(a.Symbol), int(a.Ticket), int(b.Ticket))
+
+    @translated
+    def close_all_by(self, symbol: str) -> None:
+        """Close every pair of opposite positions of ``symbol`` against each other (hedged accounts)."""
+        self._require_connected()
+        self._spec(symbol)
+        self._api.OrderMultipleCloseBy(symbol)
+
+    # ---- with a request id and progress events ------------------------------------------------------------------
+
+    @translated
+    def buy_async(self, symbol: str, lots: float, *, price: Optional[float] = None, slippage: int = 0,
+                  sl: float = 0.0, tp: float = 0.0, comment: Optional[str] = None, magic: int = 0,
+                  placed_type: Optional[str] = None) -> int:
+        """Send a market buy and return its request id as soon as the request is on the wire; the outcome arrives
+        through :meth:`on_order_progress` (and :meth:`on_order_update`)."""
+        self._require_connected()
+        pos, named = self._send_args(symbol, "Buy", lots, price, sl, tp, slippage, comment, magic, None, placed_type)
+        return int(self._trader.OrderSendAsync(*pos, **named))
+
+    @translated
+    def sell_async(self, symbol: str, lots: float, *, price: Optional[float] = None, slippage: int = 0,
+                   sl: float = 0.0, tp: float = 0.0, comment: Optional[str] = None, magic: int = 0,
+                   placed_type: Optional[str] = None) -> int:
+        """Send a market sell and return its request id at once; see :meth:`buy_async`."""
+        self._require_connected()
+        pos, named = self._send_args(symbol, "Sell", lots, price, sl, tp, slippage, comment, magic, None, placed_type)
+        return int(self._trader.OrderSendAsync(*pos, **named))
+
+    @translated
+    def place_order_async(self, symbol: str, kind: str, lots: float, price: float, *, sl: float = 0.0,
+                          tp: float = 0.0, expiration: Expiry = None, slippage: int = 0,
+                          comment: Optional[str] = None, magic: int = 0, placed_type: Optional[str] = None) -> int:
+        """Place a pending order and return its request id at once; see :meth:`place_order`."""
+        self._require_connected()
+        pos, named = self._send_args(symbol, self._pending_kind(kind), lots, price, sl, tp, slippage, comment, magic,
+                                     expiration, placed_type)
+        return int(self._trader.OrderSendAsync(*pos, **named))
+
+    @translated
+    def modify_async(self, ticket: int, *, sl: Optional[float] = None, tp: Optional[float] = None,
+                     price: Optional[float] = None, expiration: Expiry = None) -> int:
+        """Modify a position or pending order and return its request id at once; see :meth:`modify`."""
+        self._require_connected()
+        args, exp = self._modify_args(ticket, sl, tp, price, expiration)
+        ticket_, symbol, kind, lots, new_price, new_sl, new_tp = args
+        if exp is None:
+            import System  # noqa: PLC0415
+            exp = System.DateTime.MinValue
+        return int(self._trader.OrderModifyAsync(ticket_, symbol, kind, lots, new_price, new_sl, new_tp, exp))
+
+    @translated
+    def close_async(self, ticket: int, lots: Optional[float] = None, *, price: Optional[float] = None,
+                    slippage: int = 0) -> int:
+        """Close a position (or part of it) at market and return its request id at once; see :meth:`close`."""
+        self._require_connected()
+        o, amount, px = self._close_args(ticket, lots, price, slippage)
+        return int(self._trader.OrderCloseAsync(str(o.Symbol), int(o.Ticket), amount, px, int(slippage)))
+
+    @translated
+    def cancel_async(self, ticket: int) -> int:
+        """Delete a pending order and return its request id at once; see :meth:`cancel`."""
+        self._require_connected()
+        o = self._open_pending(ticket)
+        return int(self._trader.OrderCancelAsync(int(o.Ticket), o.Type, str(o.Symbol), float(o.Lots),
+                                                 float(o.OpenPrice)))
+
+    @translated
+    def close_by_async(self, ticket: int, opposite_ticket: int) -> int:
+        """:meth:`close_by`, returning its request id at once."""
+        self._require_connected()
+        a = self._open_position(ticket)
+        b = self._open_position(opposite_ticket)
+        if str(a.Symbol).lower() != str(b.Symbol).lower() or str(a.Type) == str(b.Type):
+            raise InvalidRequestError("close_by needs two opposite positions of the same symbol (%s %s / %s %s)"
+                                      % (a.Symbol, a.Type, b.Symbol, b.Type))
+        return int(self._trader.OrderCloseByAsync(str(a.Symbol), int(a.Ticket), int(b.Ticket)))
+
+    @translated
+    def close_all_by_async(self, symbol: str) -> int:
+        """:meth:`close_all_by`, returning its request id at once."""
+        self._require_connected()
+        self._spec(symbol)
+        return int(self._trader.OrderMultipleCloseByAsync(symbol))
+
+    # ---- awaitable ----------------------------------------------------------------------------------------------
+    # The synchronous calls, run on a worker thread so they never block the event loop.
+
+    async def _run(self, fn: Any, *args: Any, **kwargs: Any) -> Any:
+        return await asyncio.get_running_loop().run_in_executor(None, functools.partial(fn, *args, **kwargs))
+
+    async def abuy(self, *args: Any, **kwargs: Any) -> Order:
+        """Awaitable :meth:`buy`."""
+        return await self._run(self.buy, *args, **kwargs)
+
+    async def asell(self, *args: Any, **kwargs: Any) -> Order:
+        """Awaitable :meth:`sell`."""
+        return await self._run(self.sell, *args, **kwargs)
+
+    async def aplace_order(self, *args: Any, **kwargs: Any) -> Order:
+        """Awaitable :meth:`place_order`."""
+        return await self._run(self.place_order, *args, **kwargs)
+
+    async def amodify(self, *args: Any, **kwargs: Any) -> Order:
+        """Awaitable :meth:`modify`."""
+        return await self._run(self.modify, *args, **kwargs)
+
+    async def aclose(self, *args: Any, **kwargs: Any) -> Order:
+        """Awaitable :meth:`close`."""
+        return await self._run(self.close, *args, **kwargs)
+
+    async def acancel(self, *args: Any, **kwargs: Any) -> None:
+        """Awaitable :meth:`cancel`."""
+        return await self._run(self.cancel, *args, **kwargs)
+
+    async def aclose_by(self, *args: Any, **kwargs: Any) -> None:
+        """Awaitable :meth:`close_by`."""
+        return await self._run(self.close_by, *args, **kwargs)
+
+    async def aclose_all_by(self, *args: Any, **kwargs: Any) -> None:
+        """Awaitable :meth:`close_all_by`."""
+        return await self._run(self.close_all_by, *args, **kwargs)

pmt4api/_util.py

@@ -0,0 +1,78 @@
+"""Small helpers shared by the client modules."""
+from __future__ import annotations
+
+import functools
+import math
+from datetime import datetime
+from typing import Any, Callable, Optional
+
+from .errors import WmtError, translate
+
+
+def translated(fn: Callable) -> Callable:
+    """Re-raise the core's exceptions as the pmt4api hierarchy (the core exception stays as ``__cause__``)."""
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return fn(*args, **kwargs)
+        except WmtError:
+            raise
+        except Exception as exc:  # noqa: BLE001 — translate() returns None for anything that is not the core's
+            mapped = translate(exc)
+            if mapped is None:
+                raise
+            raise mapped from exc
+    return wrapper
+
+
+def to_core_time(value: datetime) -> Any:
+    """A naive ``datetime`` as a .NET ``DateTime`` (kind unspecified: the value is used exactly as given)."""
+    import System  # available once the runtime is loaded
+    return System.DateTime(value.year, value.month, value.day, value.hour, value.minute, value.second,
+                           value.microsecond // 1000)
+
+
+def seconds_to_ms(value: Optional[float], name: str = "timeout") -> Optional[int]:
+    """Seconds to the core's milliseconds. A timeout must be positive and finite: zero would make every call "time
+    out" the instant it is made, which for an order means "sent, unconfirmed" — an invitation to resend."""
+    if value is None:
+        return None
+    if not isinstance(value, (int, float)) or isinstance(value, bool) or not math.isfinite(value) or value <= 0:
+        raise ValueError("%s must be a positive number of seconds, not %r" % (name, value))
+    return max(1, int(round(value * 1000)))
+
+
+def finite(value: float, name: str, *, positive: bool = False, non_negative: bool = False) -> float:
+    """``value`` as a float, refusing NaN and infinity (which the core would turn into undefined volumes or prices)."""
+    v = float(value)
+    if not math.isfinite(v):
+        raise ValueError("%s must be a finite number, not %r" % (name, value))
+    if positive and v <= 0:
+        raise ValueError("%s must be positive" % name)
+    if non_negative and v < 0:
+        raise ValueError("%s must not be negative" % name)
+    return v
+
+
+def enum_value(enum_type: Any, value: Any, what: str) -> Any:
+    """Look an enum member up by name (case-insensitive, ``-``/``_``/space ignored); ``None`` stays ``None``."""
+    if value is None:
+        return None
+    key = str(value).replace("_", "").replace("-", "").replace(" ", "").lower()
+    for name in dir(enum_type):
+        if name.startswith("_"):
+            continue
+        if name.replace("_", "").lower() == key:
+            return getattr(enum_type, name)
+    raise ValueError("unknown %s %r" % (what, value))
+
+
+_PLACED = {"manual": "Client", "manually": "Client", "expert": "Expert", "dealer": "Dealer", "mobile": "Mobile",
+           "web": "Web", "signal": "Signal", "gateway": "Gateway", "api": "Api"}
+
+
+def placed_type(enum_type: Any, value: Optional[str]) -> Any:
+    """``PlacedType`` by name or by the friendly aliases ``manual`` / ``expert`` / ``dealer``."""
+    if value is None:
+        return None
+    return enum_value(enum_type, _PLACED.get(str(value).strip().lower(), value), "placed type")

pmt4api/bars.py

@@ -0,0 +1,62 @@
+"""OHLC bars: the value type and the timeframes the MT4 server serves.
+
+The server delivers each timeframe itself (it does not build it from minutes here), so only the nine MT4 timeframes
+exist. A series is returned oldest first and holds completed bars: the bar that is still forming is not part of what
+the server sends, so do not look for the current candle in it (use :meth:`Client.quote` for the live price).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Dict, Tuple, Union
+
+from .models import _time
+
+#: The timeframes the MT4 server serves, in minutes.
+TIMEFRAMES: Dict[str, int] = {"M1": 1, "M5": 5, "M15": 15, "M30": 30, "H1": 60, "H4": 240, "D1": 1440, "W1": 10080,
+                              "MN1": 43200}
+
+
+@dataclass(frozen=True)
+class Bar:
+    time: datetime              # start of the period, server time
+    open: float
+    high: float
+    low: float
+    close: float
+    volume: float               # the number of ticks in the period (MT4 reports tick volume only)
+
+    @classmethod
+    def _from_core(cls, b: Any) -> "Bar":
+        return cls(time=_time(b.Time), open=float(b.Open), high=float(b.High), low=float(b.Low),
+                   close=float(b.Close), volume=float(b.Volume))
+
+
+def timeframe_name(timeframe: Union[str, int]) -> str:
+    """The canonical name (``"H1"``) of a timeframe given by name or by its length in minutes."""
+    if isinstance(timeframe, str):
+        key = timeframe.strip().upper()
+        if key in TIMEFRAMES:
+            return key
+    elif isinstance(timeframe, int) and not isinstance(timeframe, bool):
+        for name, minutes in TIMEFRAMES.items():
+            if minutes == timeframe:
+                return name
+    raise ValueError("unsupported timeframe %r; the MT4 server serves %s" % (timeframe, ", ".join(TIMEFRAMES)))
+
+
+def timeframe_minutes(timeframe: Union[str, int]) -> int:
+    """The length in minutes of a timeframe given by name or by its length in minutes."""
+    return TIMEFRAMES[timeframe_name(timeframe)]
+
+
+@dataclass(frozen=True)
+class QuoteHistoryEvent:
+    """A chunk of bars the server delivered for a bar download (see :meth:`Client.on_quote_history`)."""
+    symbol: str
+    timeframe: str
+    bars: Tuple[Bar, ...]
+
+    @classmethod
+    def _from_core(cls, e: Any) -> "QuoteHistoryEvent":
+        return cls(symbol=str(e.Symbol), timeframe=str(e.Timeframe), bars=tuple(Bar._from_core(b) for b in (e.Bars or ())))

pmt4api/client.py

@@ -0,0 +1,143 @@
+"""The Python client: a typed, translated layer over every public capability of the licensed wmt4api core.
+
+The class is assembled from topic mixins (session, market data, account, risk, trading, events). Everything the C#
+SDK offers is reachable here by a Pythonic name; ``pmt4api.COVERAGE`` lists, member by member, where each C# member
+went, and a test fails when the core gains a member that has no entry.
+"""
+from __future__ import annotations
+
+import threading
+from typing import Any, List, Optional, Sequence, Tuple
+
+from . import _runtime
+from ._account import _AccountMixin
+from ._events import _EventsMixin
+from ._market import _MarketMixin
+from ._risk import _RiskMixin
+from ._session import _SessionMixin
+from ._trading import _TradingMixin
+from ._util import placed_type as _placed, seconds_to_ms
+
+
+def _net_encoding(name: str) -> Any:
+    """The .NET ``Encoding`` for a Python codec name (``latin-1``, ``cp1251``, ``utf-8`` ...)."""
+    import codecs
+    import re
+    try:
+        canonical = codecs.lookup(name).name
+    except LookupError as exc:
+        raise ValueError("unknown comment_encoding %r" % name) from exc
+    import System  # noqa: PLC0415 — available once the runtime is loaded
+    enc = System.Text.Encoding
+    try:                                   # the single-byte code pages are not built in: register them (idempotent)
+        import clr  # noqa: PLC0415
+        clr.AddReference("System.Text.Encoding.CodePages")
+        enc.RegisterProvider(System.Text.CodePagesEncodingProvider.Instance)
+    except Exception:  # noqa: BLE001 — an old runtime without the provider still knows Latin-1, ASCII and UTF-8
+        pass
+    attempts: List[Any] = []
+    m = re.fullmatch(r"cp(\d+)", canonical)
+    if m:
+        attempts.append(int(m.group(1)))
+    m = re.fullmatch(r"iso8859[-_]?(\d+)", canonical)
+    if m:
+        attempts.append("iso-8859-%s" % m.group(1))
+    attempts += [{"ascii": "us-ascii", "utf-8": "utf-8"}.get(canonical, canonical), name]
+    for attempt in attempts:
+        try:
+            return enc.GetEncoding(attempt)
+        except Exception:  # noqa: BLE001
+            continue
+    raise ValueError("comment_encoding %r is not available in the .NET runtime" % name)
+
+
+class Client(_SessionMixin, _MarketMixin, _AccountMixin, _RiskMixin, _TradingMixin, _EventsMixin):
+    """A connection to one MetaTrader 4 account through the licensed core.
+
+    >>> with Client(login, password, host, port, api_key="wk_...") as c:
+    ...     print(c.quote("EURUSDm"))
+
+    Credentials and library: ``api_key`` falls back to the ``WMT4API_KEY`` environment variable (then ``WMTAPI_KEY``)
+    and ``token_url`` to ``WMT4API_TOKEN_URL`` (the core reads these itself); ``dll_path`` falls back to
+    ``WMT4API_DLL``, then to the core bundled in the wheel.
+
+    Timeouts are in seconds: ``connect_timeout`` (one connect attempt on one server), ``token_timeout`` (each licence
+    request), ``trade_timeout`` (a trade confirmation; at least 1 s), ``quote_timeout`` (waiting for a quote),
+    ``history_timeout`` / ``bars_timeout`` (downloads), ``no_message_timeout`` (silence after which the session is
+    declared dead and closed: default 30 s, at least 10 s, ``0`` switches it off; the server answers a ping every few
+    seconds, so a longer silence means the link stopped carrying traffic). Every other timeout must be positive; the
+    quote, history and bars timeouts are the defaults of :meth:`quote`, :meth:`history` and :meth:`bars`. The
+    handshake with the broker has its own fixed 30 s limit, whatever ``connect_timeout`` says (that one bounds the
+    TCP dial of each server).
+
+    Reconnecting: ``auto_reconnect=True`` turns on the core's watchdog (exponential backoff, failover across the
+    primary server, ``servers`` and the broker's published list, re-subscription); tune it with ``reconnect_backoff``
+    (seconds) and ``reconnect_max_attempts`` (0 = until reconnected or ``disconnect()``). Do not poll ``connected``
+    and call ``connect()`` in a loop. ``servers`` are extra ``(host, port)`` access servers to fall back to.
+
+    ``comment_encoding`` is the codepage order comments are written in (default ``latin-1``); ``placed_type``
+    records how orders are placed (``"manual"``, ``"expert"``, ``"dealer"``; a per-call ``placed_type`` overrides it).
+
+    Callbacks run on a dispatcher thread of this client, not on the thread that created it.
+    """
+
+    def __init__(self, login: int, password: str, host: str, port: int = 443, *,
+                 api_key: Optional[str] = None, token_url: Optional[str] = None, dll_path: Optional[str] = None,
+                 connect_timeout: Optional[float] = None, token_timeout: Optional[float] = None,
+                 trade_timeout: Optional[float] = None, quote_timeout: Optional[float] = None,
+                 history_timeout: Optional[float] = None, bars_timeout: Optional[float] = None,
+                 no_message_timeout: Optional[float] = None,
+                 auto_reconnect: bool = False, reconnect_backoff: Optional[float] = None,
+                 reconnect_max_attempts: Optional[int] = None,
+                 servers: Optional[Sequence[Tuple[str, int]]] = None, comment_encoding: str = "latin-1",
+                 placed_type: Optional[str] = None):
+        core = _runtime.load(dll_path)
+        self._core = core
+        self._login = int(login)
+        self._host = host
+        self._port = int(port)
+        self._api = core.MT4API(self._login, password, host, self._port)
+        self._trader = core.OrderClient(self._api)
+        self._lock = threading.RLock()
+        self._bars_lock = threading.Lock()
+        self._handlers: List[Any] = []
+        api = self._api
+        if api_key:
+            api.ApiKey = api_key
+        if token_url:
+            api.TokenServiceUrl = token_url
+        for attr, value in (("ConnectTimeout", connect_timeout), ("TokenServiceTimeout", token_timeout),
+                            ("GetQuoteTimeoutMs", quote_timeout), ("DownloadOrderHistoryTimeoutMs", history_timeout),
+                            ("DownloadQuoteHistoryTimeout", bars_timeout), ("ReconnectBackoffMs", reconnect_backoff)):
+            ms = seconds_to_ms(value, attr)
+            if ms is not None:
+                setattr(api, attr, ms)
+        if no_message_timeout is not None:
+            if no_message_timeout == 0:
+                api.NoServerMessagesTimeout = 0          # switched off: only the operating system reports a dead link
+            else:
+                ms = seconds_to_ms(no_message_timeout, "no_message_timeout")
+                if ms < 10000:         # the heartbeat is 4 s: a shorter limit would reconnect a healthy, quiet session
+                    raise ValueError("no_message_timeout must be at least 10 seconds (or 0 to switch the watchdog off)")
+                api.NoServerMessagesTimeout = ms
+        if trade_timeout is not None:
+            ms = seconds_to_ms(trade_timeout, "trade_timeout")
+            if ms < 1000:            # the core counts whole seconds: less would give up right after sending
+                raise ValueError("trade_timeout must be at least 1 second")
+            self._trader.TradeTimeout = ms
+        if reconnect_max_attempts is not None:
+            if int(reconnect_max_attempts) < 0:
+                raise ValueError("reconnect_max_attempts must be 0 (until reconnected) or a positive number")
+            api.ReconnectMaxAttempts = int(reconnect_max_attempts)
+        if auto_reconnect:
+            api.AutoReconnect = True
+        if placed_type:
+            self._trader.PlacedType = int(_placed(core.PlacedType, placed_type))
+        self._comment_encoding = comment_encoding
+        api.Encoding = _net_encoding(comment_encoding)
+        for h, p in (servers or ()):
+            self.add_server(h, int(p))
+
+    def __repr__(self) -> str:
+        return "<pmt4api.Client login=%d host=%s:%d connected=%s>" % (
+            self._login, self._host, self._port, self.connected)