pmt5api 1.0.0__py3-none-any.whl

pmt5api/_session.py

@@ -0,0 +1,175 @@
+"""Connection lifecycle and session information."""
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime, timedelta
+from typing import Any, Optional
+
+from ._base import _Base
+from ._util import translated
+from .models import BaseInfo, _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)."""
+        if not self._api.Connected:
+            self._api.Connect()
+        return self
+
+    @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 or the server has been silent past ``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()
+
+    @translated
+    def change_password(self, new_password: str, investor: bool = False) -> None:
+        """Change the account password; with ``investor=True`` the read-only investor password instead of the main
+        one. The new password applies from the next connection."""
+        self._require_connected()
+        self._api.ChangePassword(new_password, bool(investor))
+
+    # ---- 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 a cluster member)."""
+        return str(self._api.Host or self._host)
+
+    @property
+    def port(self) -> int:
+        """The access-server port."""
+        return int(self._api.Port)
+
+    @translated
+    def base_info(self) -> BaseInfo:
+        """The server's own description of itself and of the account mode."""
+        self._require_connected()
+        return BaseInfo._from_core(self._api.Symbols.Base)
+
+    @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 pmt5api'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, kept current by incoming quotes (server time, naive); ``None`` before the first
+        connect."""
+        try:
+            return _time(self._api.ServerTime)
+        except Exception as exc:  # noqa: BLE001
+            if type(exc).__name__ == "NullReferenceException":
+                return None
+            raise
+
+    @property
+    def server_utc_offset(self) -> Optional[timedelta]:
+        """The server's offset from UTC; ``None`` before the first connect."""
+        try:
+            return timedelta(minutes=int(self._api.ServerTimeZoneInMinutes))
+        except Exception as exc:  # noqa: BLE001
+            if type(exc).__name__ == "NullReferenceException":
+                return None
+            raise
+
+    @property
+    def company(self) -> str:
+        """The broker's company name, as the server reports it."""
+        return str(self._api.AccountCompanyName or "")
+
+    @property
+    def trade_build(self) -> int:
+        """The server's trade build number."""
+        return int(self._api.ServerTradeBuild)
+
+    @property
+    def symbol_build(self) -> int:
+        """The server's symbol-database build number."""
+        return int(self._api.ServerSymBuild)
+
+    @property
+    def account_method(self) -> str:
+        """``"Hedging"`` or ``"Netting"``."""
+        return str(self._api.AccountMethod)
+
+    @property
+    def is_investor(self) -> bool:
+        """The login is the read-only investor password."""
+        return bool(self._api.IsInvestor)
+
+    @property
+    def can_trade(self) -> bool:
+        """This login may place trades: not investor, not disabled on the server, confirmed."""
+        return bool(self._api.IsTradeAllowed)
+
+    @property
+    def trading_disabled_by_server(self) -> bool:
+        """Trading is disabled for this account on the server side."""
+        return bool(self._api.IsTradeDisableOnServer)
+
+    @property
+    def is_confirmed(self) -> bool:
+        """False while the broker has not yet confirmed the account (trading is blocked until it is)."""
+        return not bool(self._api.IsNotConfirmedAccount)
+
+    @property
+    def connect_time(self) -> Optional[datetime]:
+        """When this session connected, by the local clock."""
+        return _time(self._api.ConnectTime)
+
+    @property
+    def last_quote_time(self) -> Optional[datetime]:
+        """The server timestamp of the last quote received (server time, not the local clock): compare it with
+        :attr:`server_time`, not with ``datetime.now()``."""
+        return _time(self._api.LastQuoteTime)
+
+    @property
+    def last_server_message_time(self) -> Optional[datetime]:
+        """When the server last sent anything, by the local clock: a liveness signal."""
+        return _time(self._api.LastServerMessageTime)

pmt5api/_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