pmt4api 1.0.0__py3-none-any.whl

pmt4api/_events.py

@@ -0,0 +1,189 @@
+"""Events: typed callbacks, and sync / async iterators over them.
+
+Callbacks are delivered by the per-client dispatcher in :mod:`._streams`: each event is snapshotted on the core's
+thread and called back one at a time, in arrival order, on one thread; ``Client.events_dropped`` counts events lost
+to a callback that fell too far behind.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, AsyncIterator, Callable, Iterator, Optional
+
+from ._base import _Base
+from ._streams import _AsyncQueueIterator, _Dispatcher, _QueueIterator
+from .bars import QuoteHistoryEvent
+from .errors import ConnectError, ConnectionLostError, RequestTimeout, translate
+from .models import ConnectEvent, Order, OrderProgress, OrderUpdate, Quote
+
+log = logging.getLogger("pmt4api")
+
+
+def _error(exc: Any) -> Optional[BaseException]:
+    if exc is None:
+        return None
+    mapped = translate(exc)
+    return mapped if mapped is not None else exc
+
+
+def _lost(exc: Any) -> Optional[BaseException]:
+    """Why a session ended. A drop is a lost connection whatever raised it: the silence watchdog's timeout and a
+    socket error are both :class:`ConnectionLostError`, not a request that timed out."""
+    err = _error(exc)
+    if err is None or isinstance(err, ConnectionLostError):
+        return err
+    if isinstance(err, (RequestTimeout, ConnectError)) or type(err).__name__ in (
+            "SocketException", "ObjectDisposedException", "IOException"):
+        return ConnectionLostError(str(getattr(exc, "Message", None) or err))
+    return err
+
+
+class _EventsMixin(_Base):
+    def _event_target(self, event: str) -> Any:
+        """The core object an event lives on: the order client carries ``OnOrderProgress``, the client the rest."""
+        return self._trader if event == "OnOrderProgress" else self._api
+
+    def _add_handler(self, event: str, handler: Any) -> None:
+        target = self._event_target(event)
+        ev = getattr(target, event)
+        ev += handler
+        setattr(target, event, ev)
+
+    def _remove_handler(self, event: str, handler: Any) -> None:
+        target = self._event_target(event)
+        ev = getattr(target, event)
+        ev -= handler
+        setattr(target, event, ev)
+
+    def _dispatcher(self) -> _Dispatcher:
+        with self._lock:
+            d = getattr(self, "_dispatch", None)
+            if d is None:
+                d = self._dispatch = _Dispatcher()
+            return d
+
+    def _wanted(self, symbols: Any) -> Any:
+        """The symbols a stream is about, by the broker's own spelling (ticks carry it). A name the broker does not
+        offer raises :class:`InvalidRequestError` now rather than yielding nothing for ever."""
+        self._require_connected()
+        names = {s for g in symbols for s in ([g] if isinstance(g, str) else g)}
+        return {self._canon(n) for n in names}
+
+    @property
+    def events_dropped(self) -> int:
+        """How many events were dropped because callbacks fell too far behind (see :mod:`pmt4api._streams`)."""
+        d = getattr(self, "_dispatch", None)
+        return d.dropped if d is not None else 0
+
+    def _watch(self, event: str, convert: Optional[Callable[[Any], Any]],
+               callback: Callable[..., None]) -> Callable[[], None]:
+        """Subscribe ``callback`` to a core event; returns the function that removes it."""
+        dispatcher = self._dispatcher()
+        active = {"on": True}
+
+        def deliver(value: Any) -> None:
+            if not active["on"]:
+                return
+            if convert is None:
+                callback()
+            else:
+                callback(value)
+
+        def handler(*raw: Any) -> None:
+            try:
+                value = convert(raw[1]) if convert is not None else None   # snapshot now, on the core's thread
+            except Exception:  # noqa: BLE001
+                log.exception("%s: could not convert the event", event)
+                return
+            dispatcher.submit(deliver, value, event)
+
+        with self._lock:
+            self._add_handler(event, handler)
+            self._handlers.append((event, handler))
+
+        def remove() -> None:
+            active["on"] = False
+            with self._lock:
+                if (event, handler) in self._handlers:
+                    self._handlers.remove((event, handler))
+                    self._remove_handler(event, handler)
+        return remove
+
+    # ---- callbacks ---------------------------------------------------------------------------------------------
+
+    def on_quote(self, callback: Callable[[Quote], None]) -> Callable[[], None]:
+        """Call ``callback(quote)`` for every tick of every subscribed symbol. Returns a function that removes it."""
+        return self._watch("OnQuote", Quote._from_core, callback)
+
+    def on_order_update(self, callback: Callable[[OrderUpdate], None]) -> Callable[[], None]:
+        """Call ``callback(update)`` when the server pushes a change to an order or position (opened, modified,
+        closed, a pending order placed, filled or deleted, a balance entry)."""
+        return self._watch("OnOrderUpdate", OrderUpdate._from_core, callback)
+
+    def on_order_progress(self, callback: Callable[[OrderProgress], None]) -> Callable[[], None]:
+        """Call ``callback(progress)`` as a trade request advances (see :meth:`buy_async`). Synchronous calls raise
+        their outcome instead, but they also report here under an id this client does not return."""
+        def convert(p: Any) -> OrderProgress:
+            order = p.Order
+            return OrderProgress(request_id=int(p.TempID), stage=str(p.Type),
+                                 order=Order._from_core(order) if order is not None else None,
+                                 error=_error(p.Exception))
+        return self._watch("OnOrderProgress", convert, callback)
+
+    def on_connect(self, callback: Callable[[ConnectEvent], None]) -> Callable[[], None]:
+        """Call ``callback(event)`` after every successful connect: the first one and each automatic or manual
+        reconnect (``event.connected`` is true)."""
+        return self._watch("OnConnect", lambda args: ConnectEvent(True, None), callback)
+
+    def on_disconnect(self, callback: Callable[[ConnectEvent], None]) -> Callable[[], None]:
+        """Call ``callback(event)`` once when a session ends. ``event.error`` is why a link dropped, and ``None`` when
+        you called :meth:`disconnect`. With ``auto_reconnect`` the client then reconnects by itself and
+        :meth:`on_connect` fires again."""
+        return self._watch("OnDisconnect", lambda args: ConnectEvent(False, _lost(args.Exception)), callback)
+
+    def on_quote_history(self, callback: Callable[[QuoteHistoryEvent], None]) -> Callable[[], None]:
+        """Call ``callback(event)`` as each chunk of bars of a :meth:`bars` download arrives."""
+        return self._watch("OnQuoteHistory", QuoteHistoryEvent._from_core, callback)
+
+    def on_symbols_update(self, callback: Callable[[], None]) -> Callable[[], None]:
+        """Call ``callback()`` when the server pushes a change to the symbol list; read :meth:`symbol` again (the
+        core keeps the table it loaded at connect, so a changed specification is seen at the next reconnect)."""
+        return self._watch("OnSymbolsUpdate", None, callback)
+
+    # ---- iterators ---------------------------------------------------------------------------------------------
+
+    def quotes(self, *symbols: str, timeout: Optional[float] = None, maxsize: int = 10000) -> Iterator[Quote]:
+        """Iterate live quotes of ``symbols`` (subscribing them first; with none given, every subscribed symbol).
+        Ends when ``timeout`` seconds pass without a tick. The feed is attached when this is called, not at the first
+        ``next()``. If the consumer falls behind by more than ``maxsize`` quotes the oldest are dropped."""
+        wanted = self._wanted(symbols)
+        pred = (lambda q: q.symbol in wanted) if wanted else None
+        return _QueueIterator(self.on_quote, timeout, maxsize, pred,
+                              (lambda: self.subscribe(*sorted(wanted))) if wanted else None)  # type: ignore[return-value]
+
+    def aquotes(self, *symbols: str, maxsize: int = 10000) -> AsyncIterator[Quote]:
+        """Async version of :meth:`quotes` (no timeout; ``aclose()`` or cancel the task to stop). Call it inside a
+        running event loop."""
+        wanted = self._wanted(symbols)
+        pred = (lambda q: q.symbol in wanted) if wanted else None
+        return _AsyncQueueIterator(self.on_quote, maxsize, pred,
+                                   (lambda: self.subscribe(*sorted(wanted))) if wanted else None)  # type: ignore[return-value]
+
+    def order_updates(self, *, timeout: Optional[float] = None, maxsize: int = 1000) -> Iterator[OrderUpdate]:
+        """Iterate order updates (attached when called). Ends when ``timeout`` seconds pass without one."""
+        return _QueueIterator(self.on_order_update, timeout, maxsize)  # type: ignore[return-value]
+
+    def aorder_updates(self, *, maxsize: int = 1000) -> AsyncIterator[OrderUpdate]:
+        """Async version of :meth:`order_updates`."""
+        return _AsyncQueueIterator(self.on_order_update, maxsize)  # type: ignore[return-value]
+
+    def order_progress(self, *, request_id: Optional[int] = None, timeout: Optional[float] = None,
+                       maxsize: int = 1000) -> Iterator[OrderProgress]:
+        """Iterate trade-request progress (attached when called), optionally only that of ``request_id``. Ends when
+        ``timeout`` seconds pass without an item."""
+        pred = (lambda p: p.request_id == request_id) if request_id is not None else None
+        return _QueueIterator(self.on_order_progress, timeout, maxsize, pred)  # type: ignore[return-value]
+
+    def aorder_progress(self, *, request_id: Optional[int] = None, maxsize: int = 1000) -> AsyncIterator[OrderProgress]:
+        """Async version of :meth:`order_progress`."""
+        pred = (lambda p: p.request_id == request_id) if request_id is not None else None
+        return _AsyncQueueIterator(self.on_order_progress, maxsize, pred)  # type: ignore[return-value]

pmt4api/_market.py

@@ -0,0 +1,263 @@
+"""Symbols, quotes, subscriptions, bars and per-symbol values."""
+from __future__ import annotations
+
+import asyncio
+import functools
+import math
+import time
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+from ._base import _Base
+from ._util import enum_value, to_core_time, translated
+from .bars import Bar, timeframe_minutes, timeframe_name
+from .errors import InvalidRequestError, NoQuoteError, RequestTimeout, translate
+from .models import Quote, SymbolGroup, SymbolInfo
+
+#: The most bars one request can return (the wire carries the count in a signed 16-bit field).
+MAX_BARS_PER_REQUEST = 32767
+
+
+def _names(groups: Tuple[Any, ...]) -> List[str]:
+    return [s for group in groups for s in ([group] if isinstance(group, str) else group)]
+
+
+class _MarketMixin(_Base):
+    # ---- symbols -----------------------------------------------------------------------------------------------
+
+    def _spec(self, name: str) -> Any:
+        spec = self._api.GetSymbolSpec(name)
+        if spec is None:
+            raise InvalidRequestError("unknown symbol %r" % name)
+        return spec
+
+    def _canon(self, name: str) -> str:
+        """The broker's own spelling of a symbol (the lookup ignores case; the wire, the quote cache and the events do
+        not), so ``"eurusdm"`` and ``"EURUSDm"`` are the same symbol everywhere."""
+        return str(self._spec(name).Name)
+
+    @translated
+    def symbols(self) -> Dict[str, SymbolInfo]:
+        """Every symbol the broker offers on this account, by name, with its specification."""
+        self._require_connected()
+        out: Dict[str, SymbolInfo] = {}
+        for name in self._api.GetSymbolNames():
+            spec = self._api.GetSymbolSpec(name)
+            if spec is not None:
+                out[str(spec.Name)] = SymbolInfo._from_core(spec)
+        return out
+
+    @translated
+    def symbol(self, name: str) -> SymbolInfo:
+        """One symbol's specification. Names carry the broker's suffix (``EURUSDm``, ``XAUUSD.s``): find yours with
+        :meth:`find_symbols`. The lookup ignores case."""
+        self._require_connected()
+        return SymbolInfo._from_core(self._spec(name))
+
+    @translated
+    def has_symbol(self, name: str) -> bool:
+        """Whether the broker offers ``name`` (case-insensitive)."""
+        self._require_connected()
+        return self._api.GetSymbolSpec(name) is not None
+
+    @translated
+    def find_symbols(self, prefix: str) -> List[str]:
+        """Every symbol whose name starts with ``prefix`` (case-insensitive; brokers add suffixes such as ``m`` or
+        ``.s``), exact match first, then shortest name."""
+        self._require_connected()
+        key = prefix.lower()
+        names = [str(n) for n in self._api.GetSymbolNames()]
+        return sorted((n for n in names if n.lower().startswith(key)), key=lambda n: (n.lower() != key, len(n), n))
+
+    @translated
+    def find_symbol(self, prefix: str) -> Optional[str]:
+        """The symbol ``prefix`` names: the exact name if the broker has it, else the only symbol that starts with
+        it. ``None`` when there is none; an :class:`InvalidRequestError` listing the candidates when several do
+        (use :meth:`find_symbols` and choose)."""
+        hits = self.find_symbols(prefix)
+        if not hits:
+            return None
+        if hits[0].lower() == prefix.lower() or len(hits) == 1:
+            return hits[0]
+        raise InvalidRequestError("%r is ambiguous: %s" % (prefix, ", ".join(hits[:8]) + (" ..." if len(hits) > 8 else "")))
+
+    @translated
+    def symbol_groups(self) -> List[SymbolGroup]:
+        """The broker's configured symbol groups (name and description). The core does not say which group a symbol
+        belongs to; :attr:`SymbolInfo.security_index` is the key of its volume rules."""
+        self._require_connected()
+        return [SymbolGroup._from_core(g) for g in (self._api.Groups or ())]
+
+    # ---- quotes and subscriptions ------------------------------------------------------------------------------
+
+    def _quote_ms(self, timeout: Optional[float]) -> int:
+        return int(timeout * 1000) if timeout is not None else int(self._api.GetQuoteTimeoutMs)
+
+    def _get_quote(self, symbol: str, ms: int) -> Any:
+        """The core's quote, or :class:`NoQuoteError` when none arrives in time (nothing is sent by this)."""
+        if self._api.GetSymbolSpec(symbol) is None:
+            raise InvalidRequestError("unknown symbol %r" % symbol)
+        try:
+            q = self._api.GetQuote(symbol, ms)
+        except Exception as exc:  # noqa: BLE001
+            mapped = translate(exc)
+            if isinstance(mapped, RequestTimeout):
+                raise NoQuoteError("no quote for %s within %.1f s" % (symbol, ms / 1000.0)) from exc
+            raise
+        if q is None:
+            raise NoQuoteError("no quote for %s within %.1f s" % (symbol, ms / 1000.0))
+        return q
+
+    @translated
+    def quote(self, symbol: str, timeout: Optional[float] = None) -> Quote:
+        """The current quote of one symbol, waiting up to ``timeout`` seconds (default: the client's ``quote_timeout``)
+        for the first tick; :class:`NoQuoteError` if none arrives. The price is current: a symbol that is not
+        subscribed (while others are) is subscribed first and the call waits for its next tick, so it is never a price
+        cached before the feed was narrowed. ``time`` is the tick's server time."""
+        self._require_connected()
+        return Quote._from_core(self._get_quote(self._canon(symbol), self._quote_ms(timeout)))
+
+    async def aquote(self, symbol: str, timeout: Optional[float] = None) -> Quote:
+        """Awaitable :meth:`quote` (runs on a worker thread; never blocks the event loop)."""
+        return await asyncio.get_running_loop().run_in_executor(None, functools.partial(self.quote, symbol, timeout))
+
+    @translated
+    def subscribe(self, *symbols: str) -> None:
+        """Start the live quote feed for the given symbols (names, or lists of names). A name the broker does not
+        offer raises :class:`InvalidRequestError` before anything is subscribed."""
+        self._require_connected()
+        names = _names(symbols)
+        for n in names:
+            self._spec(n)
+        for n in names:
+            self._api.Subscribe(n)
+
+    @translated
+    def unsubscribe(self, *symbols: str) -> None:
+        """Stop the live quote feed for the given symbols (names, or lists of names). A symbol with an open position
+        stays on the feed (its profit and the account's equity are priced from it); with nothing left subscribed the
+        server goes back to streaming its default set."""
+        self._require_connected()
+        for n in _names(symbols):
+            self._api.Unsubscribe(n)
+
+    @translated
+    def is_subscribed(self, symbol: str) -> bool:
+        """Whether ``symbol`` was subscribed (by :meth:`subscribe`, a quote request that had to wait, or the core
+        itself for the symbols of open positions). Before the first subscription the server streams a default set
+        of symbols, so :meth:`quote` also answers for symbols this reports as not subscribed."""
+        self._require_connected()
+        return bool(self._api.IsSubscribed(symbol))
+
+    # ---- values per symbol -------------------------------------------------------------------------------------
+
+    @translated
+    def tick_value(self, symbol: str, side: str = "ask", timeout: Optional[float] = None) -> float:
+        """The value, in account currency, of one full price unit per 1.0 lot (as the terminal computes it,
+        converting through the account currency's cross rates).
+
+        This is an *input* to position sizing, not a recipe: see :meth:`lots_for_risk`. ``side`` is ``"ask"`` (what a
+        long position is priced against) or ``"bid"`` (a short). Waits up to ``timeout`` seconds (default:
+        ``quote_timeout``) for a live quote. Raises :class:`InvalidRequestError` when the value cannot be computed (a
+        symbol whose profit currency has no conversion rate), never a NaN.
+        """
+        self._require_connected()
+        side_key = str(side).lower()
+        if side_key not in ("ask", "bid"):
+            raise ValueError("side must be 'ask' or 'bid'")
+        self._spec(symbol)
+        ms = self._quote_ms(timeout)
+        if side_key == "ask":
+            value = float(self._api.GetTickValue(symbol, ms))
+        else:
+            value = float(self._api.GetBidTickValue(self._get_quote(symbol, ms)))
+        if math.isnan(value):
+            raise InvalidRequestError("the tick value of %s cannot be computed (no conversion rate yet)" % symbol)
+        return value
+
+    @translated
+    def contract_size(self, symbol: str) -> float:
+        """The contract size of a symbol (units of the instrument per 1.0 lot)."""
+        self._require_connected()
+        return float(self._spec(symbol).ContractSize)
+
+    # ---- bars --------------------------------------------------------------------------------------------------
+
+    def _download_bars(self, symbol: str, tf: Any, end: datetime, count: int, timeout: float) -> List[Bar]:
+        """One bar request: up to ``count`` bars ending at ``end``. The core allows one request per symbol and
+        timeframe at a time; the call is serialised and bounded by ``timeout`` seconds."""
+        with self._bars_lock:
+            api = self._api
+            previous = int(api.DownloadQuoteHistoryTimeout)
+            api.DownloadQuoteHistoryTimeout = max(1, int(timeout * 1000))
+            try:
+                got = api.DownloadQuoteHistory(symbol, tf, to_core_time(end), int(count))
+            finally:
+                api.DownloadQuoteHistoryTimeout = previous
+        return [Bar._from_core(b) for b in (got or ())]
+
+    @translated
+    def bars(self, symbol: str, timeframe: Union[str, int] = "H1", *, count: Optional[int] = None,
+             start: Optional[datetime] = None, end: Optional[datetime] = None,
+             timeout: Optional[float] = None) -> List[Bar]:
+        """OHLC bars, oldest first, in the broker's server time.
+
+        Give ``count`` for the latest N bars, or ``start`` for everything from that time; with neither, the latest
+        500. ``end`` (default: now) is the moment the series is read up to: only bars that had completed by then are
+        returned (a bar that opens exactly at ``end`` is still forming and is not in it), so there is no look-ahead.
+        ``timeframe`` is one of ``M1 M5 M15 M30 H1 H4 D1 W1 MN1`` (or its length in minutes): the server serves each
+        itself. The server limits how far back it goes (about a few days of M1), so a long request may return fewer
+        bars than asked for; that is the end of the broker's history. ``timeout`` (seconds, default: the client's
+        ``bars_timeout``) bounds the whole call.
+        """
+        self._require_connected()
+        minutes = timeframe_minutes(timeframe)
+        tf = enum_value(self._core.Timeframe, timeframe_name(timeframe), "timeframe")
+        if count is not None and start is not None:
+            raise ValueError("give count or start, not both")
+        if count is not None and count <= 0:
+            raise ValueError("count must be positive")
+        if count is None and start is None:
+            count = 500
+        symbol = self._canon(symbol)
+        start = self._server_naive(start)
+        end = self._server_naive(end)
+        total = float(timeout) if timeout is not None else self._api.DownloadQuoteHistoryTimeout / 1000.0
+        if total <= 0:
+            raise ValueError("timeout must be positive")
+        deadline = time.monotonic() + total
+        server_now = self.server_time or datetime.now(timezone.utc).replace(tzinfo=None)
+        cursor = end if end is not None else server_now
+        have: Dict[datetime, Bar] = {}
+        for _ in range(64):                          # a bound: 64 requests of up to 32767 bars each
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise RequestTimeout("bars for %s not complete within %.0f s" % (symbol, total))
+            if count is not None:
+                want = min(MAX_BARS_PER_REQUEST, max(1, count - len(have)) + 1)
+            else:
+                span = (cursor - start).total_seconds() / 60.0           # type: ignore[operator]
+                want = int(min(MAX_BARS_PER_REQUEST, max(2, span / minutes + 2)))
+            page = self._download_bars(symbol, tf, cursor, want, remaining)
+            fresh = [b for b in page if b.time not in have and (end is None or b.time <= end)]
+            for b in page:
+                if end is None or b.time <= end:
+                    have.setdefault(b.time, b)
+            if not page or not fresh:
+                break                                  # the server has nothing older: the end of its history
+            first = min(b.time for b in page)
+            if count is not None and len(have) >= count:
+                break
+            if start is not None and first <= start:
+                break
+            cursor = first
+        series = [have[t] for t in sorted(have)]
+        if start is not None:
+            series = [b for b in series if b.time >= start]
+        if count is not None:
+            series = series[-count:]
+        return series
+
+    async def abars(self, *args: Any, **kwargs: Any) -> List[Bar]:
+        """Awaitable :meth:`bars` (runs on a worker thread; never blocks the event loop)."""
+        return await asyncio.get_running_loop().run_in_executor(None, functools.partial(self.bars, *args, **kwargs))