pmt4api 1.0.0__py3-none-any.whl

pmt4api/_risk.py

@@ -0,0 +1,66 @@
+"""Position sizing, margin and P/L arithmetic that the core computes for the account's own conventions."""
+from __future__ import annotations
+
+import math
+from typing import Optional
+
+from ._base import _Base
+from ._util import enum_value, finite, translated
+from .errors import InvalidRequestError
+from .models import LotSizing
+
+
+class _RiskMixin(_Base):
+    @translated
+    def lots_for_risk(self, symbol: str, entry_price: float, stop_price: float, risk_amount: float, *,
+                      lot_step: Optional[float] = None, min_lot: Optional[float] = None,
+                      max_ratio: Optional[float] = None, max_equity_share: Optional[float] = None,
+                      max_lot: Optional[float] = None) -> LotSizing:
+        """The volume that loses ``risk_amount`` (account currency) if ``stop_price`` is hit, with the evidence.
+
+        The value of a price unit comes from :meth:`tick_value` and the broker's step / minimum / maximum volume from
+        the account's own group (pass one to override it); a size that cannot be justified is refused, not guessed.
+        The volume is rounded **down** to the step. Check ``ok``: when false, ``lots`` is 0 and ``reason`` says which
+        check failed. Amounts are in the currency the account reports (no cent-account scaling is applied: check the
+        first result against your terminal).
+        """
+        self._require_connected()
+        kwargs = {}
+        for key, value in (("lotStep", lot_step), ("minLot", min_lot), ("maxRatio", max_ratio),
+                           ("maxEquityShare", max_equity_share), ("maxLot", max_lot)):
+            if value is not None:
+                kwargs[key] = float(value)
+        result = self._api.CalculateLots(symbol, float(entry_price), float(stop_price), float(risk_amount), **kwargs)
+        return LotSizing._from_core(result)
+
+    @translated
+    def required_margin(self, symbol: str, lots: float, side: str = "buy", price: float = 0.0) -> float:
+        """The margin needed to open ``lots`` of ``symbol``, computed as the terminal does (``price`` 0 = the live
+        quote; Forex uses the account leverage, CFD the symbol's margin divider). Raises :class:`InvalidRequestError`
+        when it cannot be computed (a Futures symbol, whose formula is not verified, or no conversion rate yet)."""
+        self._require_connected()
+        key = str(side).strip().lower()
+        if key not in ("buy", "sell"):
+            raise ValueError("side must be 'buy' or 'sell'")
+        self._spec(symbol)
+        kind = enum_value(self._core.OrderType, key, "side")
+        value = float(self._api.RequiredMargin(symbol, finite(lots, "lots", positive=True), kind,
+                                               finite(price, "price", non_negative=True)))
+        if math.isnan(value) or value <= 0.0:
+            raise InvalidRequestError("the margin of %s cannot be computed (a Futures symbol, or no conversion rate "
+                                      "yet)" % symbol)
+        return value
+
+    @translated
+    def order_profit(self, symbol: str, open_price: float, close_price: float, lots: float, buy: bool = True) -> float:
+        """The P/L, in account currency, of ``lots`` moving from ``open_price`` to ``close_price``. For reporting a
+        completed or hypothetical move; use :meth:`lots_for_risk` to size. Raises :class:`InvalidRequestError` when the
+        value cannot be computed (no conversion rate yet)."""
+        self._require_connected()
+        self._spec(symbol)
+        value = float(self._api.CalculateOrderProfit(symbol, finite(open_price, "open_price"),
+                                                     finite(close_price, "close_price"),
+                                                     finite(lots, "lots", positive=True), bool(buy)))
+        if math.isnan(value):
+            raise InvalidRequestError("the profit of %s cannot be computed (no conversion rate yet)" % symbol)
+        return value

pmt4api/_runtime.py

@@ -0,0 +1,154 @@
+"""Locates the .NET runtime and the licensed core library and loads them once per process."""
+from __future__ import annotations
+
+import glob
+import importlib
+import os
+import shutil
+import sys
+import threading
+from pathlib import Path
+from typing import Iterator, Optional
+
+from .errors import CoreNotFoundError, RuntimeNotFoundError
+
+#: Environment variable that points at wmt4api.dll.
+ENV_DLL = "WMT4API_DLL"
+
+_NAMESPACE = "wmt4api"      # the .NET namespace of the core; NOT the name of this Python package
+_PKG = Path(__file__).resolve().parent
+_BUNDLED_RUNTIME = _PKG / "_dotnet"     # present in the platform wheels: host/fxr + shared/Microsoft.NETCore.App
+_lock = threading.Lock()
+_core = None
+_dll: Optional[Path] = None
+
+
+def find_dll(explicit=None) -> Path:
+    """The core library to load: the caller's path, else ``WMTAPI_DLL``, else the one bundled in the wheel.
+
+    A path the caller gave explicitly (argument or environment) is never silently replaced by another: if it does not
+    exist that is an error.
+    """
+    requested = explicit or os.environ.get(ENV_DLL)
+    if requested:
+        path = Path(requested)
+        if path.is_file():
+            return path
+        raise CoreNotFoundError("wmt4api.dll was not found at %s (from %s)" %
+                                (path, "dll_path" if explicit else ENV_DLL))
+    bundled = _PKG / "_native" / "wmt4api.dll"
+    if bundled.is_file():
+        return bundled
+    raise CoreNotFoundError(
+        "wmt4api.dll was not found. Pass dll_path=..., or set the " + ENV_DLL + " environment variable to the DLL "
+        "taken from your wmt4api package, or install a pmt4api wheel that bundles it (looked for " + str(bundled) + ")."
+    )
+
+
+def _dotnet_root_candidates() -> Iterator[Path]:
+    exe = shutil.which("dotnet")
+    if exe:
+        yield Path(exe).resolve().parent
+    home = Path.home()
+    yield home / ".dotnet"
+    for p in ("/usr/share/dotnet", "/usr/lib/dotnet", "/usr/local/share/dotnet", "/opt/dotnet"):
+        yield Path(p)
+    pf = os.environ.get("ProgramFiles")
+    if pf:
+        yield Path(pf) / "dotnet"
+
+
+def _icu_present() -> bool:
+    """True when a system ICU library is installed (the .NET runtime needs one unless globalization is invariant)."""
+    patterns = ("/usr/lib*/libicuuc.so*", "/usr/lib/*-linux-gnu/libicuuc.so*", "/lib*/libicuuc.so*",
+                "/lib/*-linux-gnu/libicuuc.so*", "/usr/local/lib*/libicuuc.so*", "/opt/homebrew/lib/libicuuc*",
+                "/usr/lib/libicuuc*")
+    return any(glob.glob(p) for p in patterns)
+
+
+def _ensure_dotnet_root() -> None:
+    """Point the runtime host at a .NET runtime: the caller's ``DOTNET_ROOT``, else the one bundled in this package,
+    else an installed one. Say so clearly when there is none."""
+    # Without an ICU library the runtime aborts the whole process (uncatchably) at start-up unless globalization is
+    # invariant. The core does not depend on culture-specific behaviour, so on a machine with no ICU ask for invariant
+    # mode — whichever runtime is used, and including a DOTNET_ROOT inherited from a parent process.
+    if sys.platform.startswith("linux") and not _icu_present():
+        os.environ.setdefault("DOTNET_SYSTEM_GLOBALIZATION_INVARIANT", "1")
+    if os.environ.get("DOTNET_ROOT"):
+        return
+    if (_BUNDLED_RUNTIME / "shared" / "Microsoft.NETCore.App").is_dir():
+        os.environ["DOTNET_ROOT"] = str(_BUNDLED_RUNTIME)
+        return
+    for root in _dotnet_root_candidates():
+        if (root / "shared" / "Microsoft.NETCore.App").is_dir():
+            os.environ["DOTNET_ROOT"] = str(root)
+            return
+    raise RuntimeNotFoundError(
+        "No .NET runtime was found. Install the .NET 8 (or later) runtime, or set DOTNET_ROOT to its install directory."
+    )
+
+
+def runtime_root() -> Optional[Path]:
+    """The .NET root in use (after ``load``), or None."""
+    root = os.environ.get("DOTNET_ROOT")
+    return Path(root) if root else None
+
+
+def _has_entry(path_entry: str, name: str) -> bool:
+    base = path_entry or os.getcwd()
+    try:
+        return os.path.isdir(os.path.join(base, name))
+    except OSError:
+        return False
+
+
+def _import_namespace():
+    """Import the core's .NET namespace even if a same-named folder is lying around on sys.path."""
+    mod = sys.modules.get(_NAMESPACE)
+    if mod is not None and hasattr(mod, "MT4API"):
+        return mod
+    sys.modules.pop(_NAMESPACE, None)
+    saved = list(sys.path)
+    try:
+        sys.path[:] = [p for p in sys.path if not _has_entry(p, _NAMESPACE)]
+        importlib.invalidate_caches()
+        mod = importlib.import_module(_NAMESPACE)
+    finally:
+        sys.path[:] = saved
+    if not hasattr(mod, "MT4API"):
+        raise CoreNotFoundError("the loaded library does not expose MT4API; is it the wmt4api package?")
+    return mod
+
+
+def load(dll_path=None):
+    """Load the runtime and the core (idempotent, thread-safe). Returns the core's .NET namespace module."""
+    global _core, _dll
+    with _lock:
+        if _core is not None:
+            if dll_path is not None and _dll is not None and Path(dll_path).resolve() != _dll.resolve():
+                raise CoreNotFoundError(
+                    "a different core is already loaded in this process (%s); one process can use one core, "
+                    "so dll_path=%s was not loaded" % (_dll, dll_path))
+            return _core
+        dll = find_dll(dll_path)
+        _ensure_dotnet_root()
+        try:
+            from pythonnet import load as _load
+            _load("coreclr")
+            import clr  # noqa: F401  (provided by pythonnet)
+        except Exception as e:  # noqa: BLE001 — anything here means the runtime could not start
+            raise RuntimeNotFoundError("could not start the .NET runtime: %s" % e) from e
+        import clr as _clr
+        from System.Reflection import Assembly      # available once the runtime is up
+        try:
+            Assembly.LoadFrom(str(dll))             # AddReference(<absolute path>) fails on pythonnet 3.0.x
+        except Exception as e:  # noqa: BLE001
+            raise CoreNotFoundError("could not load %s: %s" % (dll, e)) from e
+        _clr.AddReference("wmt4api")                # now by name: registers the namespace for `import`
+        _core = _import_namespace()
+        _dll = dll
+        return _core
+
+
+def loaded_dll() -> Optional[Path]:
+    return _dll

pmt4api/_session.py

@@ -0,0 +1,171 @@
+"""Connection lifecycle and session information."""
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime, timedelta, timezone
+from typing import Any, List, Optional, Tuple
+
+from ._base import _Base
+from ._util import translated
+from .errors import ConnectError, RequestTimeout
+from .models import _time
+
+
+class _SessionMixin(_Base):
+    # ---- lifecycle ---------------------------------------------------------------------------------------------
+
+    @translated
+    def connect(self) -> "_SessionMixin":
+        """Connect, authorise through the licence service and load the account. Returns ``self``. Calling it on a
+        client that is already connected does nothing (it never opens a second session).
+
+        Raises :class:`LicenseError` / :class:`TokenServiceError` when the licence is refused or unreachable,
+        :class:`LoginRejectedError` when the broker rejects the account or password, and :class:`ConnectError` when
+        no access server could be reached within ``connect_timeout``.
+        """
+        if self._api.Connected:
+            return self
+        try:
+            self._api.Connect()
+        except Exception as exc:  # noqa: BLE001
+            # a dial that timed out is a connect failure, not "a request was sent and not confirmed"
+            from .errors import translate
+            mapped = translate(exc)
+            if isinstance(mapped, RequestTimeout):
+                raise ConnectError(str(mapped)) from exc
+            raise
+        return self
+
+    @translated
+    def reconnect(self) -> bool:
+        """Re-establish a dropped session over the primary server, ``servers`` and the list the broker published, and
+        restore the quote subscriptions. ``True`` when connected afterwards (also when it already was), ``False`` when
+        every server failed — try again later. A refusal retrying cannot cure (an expired licence, a rejected login)
+        also returns ``False``: call :meth:`connect` to see the reason."""
+        return bool(self._api.Reconnect())
+
+    @translated
+    def disconnect(self) -> None:
+        """Close the session and stop the core's reconnect watchdog for good — also when the link is down and the
+        watchdog is mid-way through reconnecting. Harmless when never connected."""
+        try:
+            self._api.Disconnect()
+        except Exception as exc:  # noqa: BLE001
+            if type(exc).__name__ != "NullReferenceException":      # never connected: nothing to close
+                raise
+
+    @property
+    def connected(self) -> bool:
+        """Live: false when the socket died (the core notices a closed or reset connection at once and a silent one
+        within ``no_message_timeout``)."""
+        return bool(self._api.Connected)
+
+    def __enter__(self) -> "_SessionMixin":
+        return self.connect()
+
+    def __exit__(self, *exc: Any) -> None:
+        self.disconnect()
+
+    async def aconnect(self) -> "_SessionMixin":
+        """Awaitable :meth:`connect`; the blocking connect runs on a worker thread."""
+        return await asyncio.get_running_loop().run_in_executor(None, self.connect)
+
+    async def adisconnect(self) -> None:
+        """Awaitable :meth:`disconnect`."""
+        await asyncio.get_running_loop().run_in_executor(None, self.disconnect)
+
+    async def __aenter__(self) -> "_SessionMixin":
+        return await self.aconnect()
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.adisconnect()
+
+    # ---- information -------------------------------------------------------------------------------------------
+
+    @property
+    def login(self) -> int:
+        """The account login number."""
+        return int(self._api.User)
+
+    @property
+    def host(self) -> str:
+        """The access server this client was created for (it may fail over to another of :attr:`server_list`)."""
+        return str(self._api.Host or self._host)
+
+    @property
+    def port(self) -> int:
+        """The access-server port."""
+        return int(self._api.Port)
+
+    @property
+    def server_list(self) -> List[Tuple[str, int]]:
+        """The access servers the broker published at the last connect, as ``(host, port)``: the pool a reconnect
+        fails over across (empty before the first connect)."""
+        return [(str(t.Item1), int(t.Item2)) for t in self._api.SrvList]
+
+    @property
+    def servers(self) -> List[Tuple[str, int]]:
+        """The extra access servers given with ``servers=`` / :meth:`add_server`, tried after the primary one."""
+        return [(str(t.Item1), int(t.Item2)) for t in self._api.Servers]
+
+    @translated
+    def add_server(self, host: str, port: int = 443) -> None:
+        """Add a backup access server, tried (in order) when the primary one cannot be dialled. Credential
+        rejections do not fail over. Takes effect at the next connect."""
+        if not host:
+            raise ValueError("host must not be empty")
+        import System  # noqa: PLC0415
+        self._api.Servers.Add(System.ValueTuple[System.String, System.Int32](str(host), int(port)))
+
+    @property
+    def raw(self) -> Any:
+        """The underlying core object, for anything this layer does not wrap. Calls made on it raise the core's own
+        exceptions, not pmt4api's."""
+        return self._api
+
+    @property
+    def core_version(self) -> str:
+        """The version of the licensed core library in use."""
+        return str(self._api.GetType().Assembly.GetName().Version)
+
+    @property
+    def server_time(self) -> Optional[datetime]:
+        """The server's clock (server time, naive): the local UTC clock moved by the server's offset. ``None`` before
+        the first connect."""
+        if self._api.Account is None:
+            return None
+        return _time(self._api.ServerTime)
+
+    @property
+    def server_utc_offset(self) -> Optional[timedelta]:
+        """The server's offset from UTC, in whole hours as the broker configures it; ``None`` before the first
+        connect."""
+        st = self.server_time
+        if st is None:
+            return None
+        delta = st - datetime.now(timezone.utc).replace(tzinfo=None)
+        return timedelta(hours=round(delta.total_seconds() / 3600.0))
+
+    @property
+    def company(self) -> str:
+        """The broker's company name, as the server reports it (empty before the first connect)."""
+        a = self._api.Account
+        return str(a.Company or "") if a is not None else ""
+
+    @property
+    def trade_build(self) -> int:
+        """The server's build number for this session."""
+        return int(self._api.ServerTradeBuild)
+
+    @property
+    def is_investor(self) -> bool:
+        """The login is the read-only investor password, as the account record reports it (the field the C# client
+        reads): every trading call then raises :class:`InvestorModeError` before anything is sent. (Verified on
+        trading logins only: no investor password was available to exercise the true case.)"""
+        return bool(self._api.IsInvestor)
+
+    @property
+    def can_trade(self) -> bool:
+        """Connected with a trading (not investor) password. The broker may still refuse a particular symbol or
+        time; this only says the session is allowed to try. See :attr:`is_investor`."""
+        return bool(self._api.Connected) and not bool(self._api.IsInvestor)

pmt4api/_streams.py

@@ -0,0 +1,238 @@
+"""Delivery machinery shared by the event API: one dispatcher thread per client, and the sync / async iterators.
+
+The core delivers each event on its own thread-pool task, so events can arrive concurrently and slightly out of order,
+and a slow callback would pile up threads. The client therefore converts every event to a plain value the moment it
+arrives (a snapshot — the core's objects are shared and mutable) and hands it to ONE dispatcher thread per client,
+which calls the callbacks one at a time, in arrival order. A callback may take its time; if it falls more than
+``EVENT_QUEUE`` events behind, the oldest events are dropped (a warning is logged, and ``Client.events_dropped``
+counts them). An exception raised by a callback is logged (under the package's own logger name) and swallowed so it
+cannot break the connection.
+
+This file is identical in pmt5api and pmt4api (a repository test keeps them so).
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import queue
+import threading
+import weakref
+from typing import Any, Callable, Optional, Tuple
+
+_PACKAGE = __name__.split(".")[0]
+log = logging.getLogger(_PACKAGE)
+
+#: How many events may wait for the dispatcher before the oldest are dropped.
+EVENT_QUEUE = 20000
+
+
+class _Dispatcher:
+    """One thread that runs a client's callbacks in arrival order."""
+
+    def __init__(self) -> None:
+        self._q: "queue.Queue[Tuple[Callable[[Any], None], Any, str]]" = queue.Queue(maxsize=EVENT_QUEUE)
+        self.dropped = 0
+        self._count_lock = threading.Lock()
+        self._thread = threading.Thread(target=self._run, name=_PACKAGE + "-events", daemon=True)
+        self._thread.start()
+
+    def submit(self, fn: Callable[[Any], None], arg: Any, event: str) -> None:
+        while True:
+            try:
+                self._q.put_nowait((fn, arg, event))
+                return
+            except queue.Full:
+                try:
+                    self._q.get_nowait()
+                except queue.Empty:
+                    continue
+                with self._count_lock:
+                    self.dropped += 1
+                    total = self.dropped
+                if total == 1 or total % 1000 == 0:
+                    log.warning("event queue full: %d event(s) dropped so far; a callback is too slow", total)
+
+    def _run(self) -> None:
+        while True:
+            fn, arg, event = self._q.get()
+            try:
+                fn(arg)
+            except Exception:  # noqa: BLE001 — keep the dispatcher alive
+                log.exception("%s callback raised", event)
+
+
+_END = object()          # put on a queue to wake a consumer that is blocked in it when the iterator is closed
+
+
+class _QueueIterator:
+    """An iterator over an event stream. It subscribes when it is created (not at the first ``next()``), so nothing
+    that happens after the call is missed, and unsubscribes when exhausted or closed."""
+
+    def __init__(self, register: Callable[[Callable[[Any], None]], Callable[[], None]], timeout: Optional[float],
+                 maxsize: int, predicate: Optional[Callable[[Any], bool]] = None,
+                 setup: Optional[Callable[[], None]] = None) -> None:
+        self._q: "queue.Queue[Any]" = queue.Queue(maxsize=maxsize)
+        self._timeout = timeout
+        self._pred = predicate
+        self._closed = False
+        ref = weakref.ref(self)
+
+        def put(item: Any) -> None:            # weakly bound: an abandoned iterator can be collected, and then detaches
+            it = ref()
+            if it is not None:
+                it._put(item)
+
+        self._remove = register(put)
+        if setup is not None:
+            try:
+                setup()
+            except BaseException:
+                self.close()
+                raise
+
+    def _put(self, item: Any) -> None:
+        if self._pred is not None and not self._pred(item):
+            return
+        while True:
+            try:
+                self._q.put_nowait(item)
+                return
+            except queue.Full:
+                try:
+                    self._q.get_nowait()
+                except queue.Empty:
+                    pass
+
+    def __iter__(self) -> "_QueueIterator":
+        return self
+
+    def __next__(self) -> Any:
+        if self._closed:
+            raise StopIteration
+        try:
+            item = self._q.get(timeout=self._timeout)
+        except queue.Empty:
+            self.close()
+            raise StopIteration
+        if item is _END:
+            raise StopIteration
+        return item
+
+    def close(self) -> None:
+        if not self._closed:
+            self._closed = True
+            self._remove()
+            while True:                          # wake a thread that is blocked in next(), whatever is queued
+                try:
+                    self._q.put_nowait(_END)
+                    return
+                except queue.Full:
+                    try:
+                        self._q.get_nowait()
+                    except queue.Empty:
+                        pass
+
+    def __enter__(self) -> "_QueueIterator":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def __del__(self) -> None:  # pragma: no cover - best effort
+        try:
+            self.close()
+        except Exception:  # noqa: BLE001
+            pass
+
+
+class _AsyncQueueIterator:
+    """The asyncio counterpart; created inside a running loop, subscribed at creation, ``aclose()`` to stop."""
+
+    def __init__(self, register: Callable[[Callable[[Any], None]], Callable[[], None]], maxsize: int,
+                 predicate: Optional[Callable[[Any], bool]] = None,
+                 setup: Optional[Callable[[], None]] = None) -> None:
+        self._loop = asyncio.get_running_loop()
+        self._q: "asyncio.Queue[Any]" = asyncio.Queue(maxsize=maxsize)
+        self._pred = predicate
+        self._closed = False
+        ref = weakref.ref(self)
+        loop = self._loop
+
+        def push(item: Any) -> None:           # weakly bound, as in the synchronous iterator
+            it = ref()
+            if it is not None:
+                try:
+                    loop.call_soon_threadsafe(it._push, item)
+                except RuntimeError:           # the loop is closed
+                    pass
+
+        self._remove = register(push)
+        if setup is not None:
+            try:
+                setup()
+            except BaseException:
+                self._finish()
+                raise
+
+    def _push(self, item: Any) -> None:
+        if self._closed or (self._pred is not None and not self._pred(item)):
+            return
+        if self._q.full():
+            try:
+                self._q.get_nowait()
+            except asyncio.QueueEmpty:
+                pass
+        try:
+            self._q.put_nowait(item)
+        except asyncio.QueueFull:
+            pass
+
+    def _finish(self) -> None:
+        if not self._closed:
+            self._closed = True
+            self._remove()
+            try:                                  # wake a task that is awaiting the next item
+                self._loop.call_soon_threadsafe(self._wake)
+            except RuntimeError:                  # the loop is closed: nobody is waiting
+                pass
+
+    def _wake(self) -> None:
+        if self._q.full():
+            try:
+                self._q.get_nowait()
+            except asyncio.QueueEmpty:
+                pass
+        try:
+            self._q.put_nowait(_END)
+        except asyncio.QueueFull:
+            pass
+
+    def __aiter__(self) -> "_AsyncQueueIterator":
+        return self
+
+    async def __anext__(self) -> Any:
+        if self._closed and self._q.empty():
+            raise StopAsyncIteration
+        try:
+            item = await self._q.get()
+        except asyncio.CancelledError:
+            self._finish()
+            raise
+        if item is _END:
+            raise StopAsyncIteration
+        return item
+
+    async def aclose(self) -> None:
+        self._finish()
+
+    async def __aenter__(self) -> "_AsyncQueueIterator":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        self._finish()
+
+    def __del__(self) -> None:  # pragma: no cover - best effort when a loop is abandoned without aclose()
+        try:
+            self._finish()
+        except Exception:  # noqa: BLE001
+            pass