pmt5api 1.0.0__py3-none-any.whl

pmt5api/__init__.py

@@ -0,0 +1,34 @@
+"""pmt5api — Python access to the wmt5api MetaTrader 5 client library.
+
+A typed, translated layer over every public capability of the licensed C# core (loaded in-process): the protocol,
+licensing and trading logic stay in the core; this package adds a Pythonic surface — plain data types, a small error
+hierarchy, context managers, sync and async streams, bars, sizing and order entry.
+"""
+from ._coverage import COVERAGE, TYPES
+from .bars import Bar, QuoteHistoryEvent, TIMEFRAMES, aggregate
+from .client import Client, Proxy
+from .diagnostics import enable_core_logging
+from .errors import (BusyError, ConnectError, NoQuoteError, ConnectionLostError, CoreNotFoundError, InvalidRequestError, InvestorModeError,
+                     LicenseError, NotConnectedError, ProxyError, RequestTimeout, RuntimeNotFoundError,
+                     ServerError, TokenServiceError, WmtError)
+from .frames import to_frame
+from .models import (AccountInfo, AccountSummary, BaseInfo, CommissionInfo, CommissionTier, ConnectEvent, Deal,
+                     DemoAccount, DemoAccountRequest, EquityPoint, History, LotSizing, Order, OrderProgress,
+                     OrderUpdate, Quote, ServerRecord, SymbolInfo, SymbolSessions, TradingSession)
+from .servers import load_servers_dat, request_demo_account, save_servers_dat, tick_value_from_deal
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "Client", "Proxy",
+    "Quote", "SymbolInfo", "SymbolSessions", "TradingSession", "CommissionInfo", "CommissionTier", "BaseInfo",
+    "AccountInfo", "AccountSummary", "EquityPoint", "LotSizing", "Order", "Deal", "History",
+    "OrderUpdate", "OrderProgress", "ConnectEvent", "QuoteHistoryEvent",
+    "ServerRecord", "DemoAccountRequest", "DemoAccount",
+    "Bar", "TIMEFRAMES", "aggregate", "to_frame",
+    "load_servers_dat", "save_servers_dat", "request_demo_account", "tick_value_from_deal", "enable_core_logging",
+    "WmtError", "LicenseError", "TokenServiceError", "ConnectError", "ConnectionLostError", "NotConnectedError",
+    "ServerError", "InvestorModeError", "ProxyError", "RequestTimeout", "NoQuoteError", "InvalidRequestError", "BusyError",
+    "CoreNotFoundError",
+    "RuntimeNotFoundError", "COVERAGE", "TYPES", "__version__",
+]

pmt5api/__main__.py

@@ -0,0 +1,78 @@
+"""``python -m pmt5api`` — what is installed, and whether it works on this machine.
+
+    python -m pmt5api                 offline: versions, the core, the .NET runtime, this platform
+    python -m pmt5api --connect       also connect read-only using PMT5_LOGIN, PMT5_PASSWORD, PMT5_HOST[, PMT5_PORT]
+                                      and WMTAPI_KEY, and print the account's currency, leverage and symbol count
+
+The output contains no secrets; it is what to send when asking for help.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import platform
+import sys
+from typing import List, Optional
+
+from . import __version__, _runtime
+from .errors import WmtError
+
+
+def _key_hint() -> str:
+    key = os.environ.get("WMTAPI_KEY", "")
+    if not key:
+        return "not set (WMTAPI_KEY)"
+    return "set (%s…, %d characters)" % (key[:3], len(key))
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    ap = argparse.ArgumentParser(prog="python -m pmt5api", description=__doc__.split("\n\n")[0])
+    ap.add_argument("--connect", action="store_true", help="also connect read-only and read the account")
+    args = ap.parse_args(argv)
+    ok = True
+
+    print("pmt5api %s" % __version__)
+    print("python  %s on %s" % (sys.version.split()[0], platform.platform()))
+    try:
+        _runtime.load()
+    except WmtError as e:
+        print("core    NOT LOADED: %s: %s" % (type(e).__name__, e))
+        return 1
+    print("core    %s" % _runtime.loaded_dll())
+    root = _runtime.runtime_root()
+    bundled = root is not None and "_dotnet" in str(root)
+    print("runtime %s%s" % (root, " (bundled in the wheel)" if bundled else ""))
+    print("icu     %s; invariant globalization %s" % (
+        "present" if _runtime._icu_present() else "absent",
+        os.environ.get("DOTNET_SYSTEM_GLOBALIZATION_INVARIANT", "off")))
+    print("key     %s" % _key_hint())
+    docs = _runtime.loaded_dll().parent / "docs" if _runtime.loaded_dll() is not None else None
+    if docs is not None and docs.is_dir():
+        print("docs    %s (LICENSING.md, SECURITY.md, ERRORS.md)" % docs)
+
+    from .client import Client
+    c = Client(1, "x", "127.0.0.1", 1)
+    print("offline construct client: ok (core version %s)" % c.core_version)
+
+    if args.connect:
+        try:
+            login, password, host = (int(os.environ["PMT5_LOGIN"]), os.environ["PMT5_PASSWORD"],
+                                     os.environ["PMT5_HOST"])
+        except KeyError as e:
+            print("connect SKIPPED: environment variable %s is not set" % e)
+            return 0
+        port = int(os.environ.get("PMT5_PORT", "443"))
+        try:
+            with Client(login, password, host, port, connect_timeout=45) as live:
+                a = live.account()
+                print("connect ok: %s, %s, leverage 1:%d, %d symbols, mode %s, trading %s"
+                      % (live.company, a.currency, a.leverage, len(live.symbols()), live.account_method,
+                         "allowed" if live.can_trade else "not allowed (investor or disabled)"))
+        except WmtError as e:
+            ok = False
+            print("connect FAILED: %s: %s" % (type(e).__name__, e))
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pmt5api/_account.py

@@ -0,0 +1,146 @@
+"""The account: balances, positions, orders, history, and the curves derived from them."""
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import List, Optional
+
+from ._base import _Base
+from ._util import enum_value, to_core_time, translated
+from .errors import NotConnectedError
+from .models import AccountInfo, AccountSummary, EquityPoint, History, Order
+
+
+class _AccountMixin(_Base):
+    @translated
+    def account(self, refresh: bool = True) -> AccountInfo:
+        """Account details. With ``refresh`` (the default) the equity, profit and margin figures are brought up to date
+        first: every open position's symbol is quoted once and the profits are recalculated."""
+        self._require_connected()
+        api = self._api
+        if refresh:
+            symbols = {o.Symbol for o in api.GetOpenedOrders() if o.Symbol}
+            for s in symbols:
+                if not api.Connected:                  # never let a refresh trigger a connect of its own
+                    raise NotConnectedError("the connection was lost while refreshing the account")
+                try:
+                    api.GetQuote(s, 3000)
+                except Exception:  # noqa: BLE001 — a quiet symbol must not block the account snapshot
+                    pass
+            if not api.Connected:
+                raise NotConnectedError("the connection was lost while refreshing the account")
+            api.UpdateProfits()
+        a = api.Account
+        return AccountInfo(
+            login=int(a.Login), name=str(a.UserName or ""), currency=str(api.AccountCurrency or ""),
+            leverage=int(a.Leverage), balance=float(a.Balance), credit=float(a.Credit),
+            equity=float(api.AccountEquity), profit=float(api.AccountProfit), margin=float(api.AccountMargin),
+            free_margin=float(api.AccountFreeMargin), margin_level=float(api.AccountMarginLevel),
+            floating_pl=float(api.AccountFloatingProfit), swap=float(api.AccountSwap),
+            commission=float(api.AccountCommission), fee=float(api.AccountFee), blocked=float(a.Blocked),
+            company=str(api.AccountCompanyName or ""), method=str(api.AccountMethod), account_type=str(a.Type or ""),
+            trade_flags=int(a.TradeFlags), country=str(a.Country or ""), city=str(a.City or ""),
+            state=str(a.State or ""), zip_code=str(a.ZipCode or ""), address=str(a.UserAddress or ""),
+            phone=str(a.Phone or ""), email=str(a.Email or ""),
+        )
+
+    @translated
+    def update_profits(self) -> None:
+        """Recompute floating P/L and used margin from the current quotes. Warm the open positions' quotes first (or
+        use ``account(refresh=True)``, which does both)."""
+        self._require_connected()
+        self._api.UpdateProfits()
+
+    # ---- orders and positions ----------------------------------------------------------------------------------
+
+    @translated
+    def orders(self) -> List[Order]:
+        """Everything currently working: open positions and pending orders."""
+        self._require_connected()
+        return [Order._from_core(o) for o in self._api.GetOpenedOrders()]
+
+    def positions(self) -> List[Order]:
+        """Open positions only (pending orders excluded).
+
+        A position is an order of type ``Buy`` or ``Sell``; pending orders are the ``*Limit`` and ``*Stop`` types. The
+        order's ``state`` is not used: the core can leave a freshly opened position in ``Started`` for a long time.
+        """
+        return [o for o in self.orders() if o.order_type in ("Buy", "Sell")]
+
+    @translated
+    def closed_orders(self) -> List[Order]:
+        """The orders this session has seen close (a rolling cache of about ten). For anything older use
+        :meth:`history`."""
+        self._require_connected()
+        return [Order._from_core(o) for o in self._api.ClosedOrders()]
+
+    # ---- history -----------------------------------------------------------------------------------------------
+
+    @translated
+    def history(self, start: Optional[datetime] = None, end: Optional[datetime] = None,
+                timeout: Optional[float] = None) -> History:
+        """Orders and deals between ``start`` and ``end`` (default: the last 30 days up to now). Blocks until the
+        server has sent everything, up to ``timeout`` seconds (default: the client's ``history_timeout``).
+
+        Naive datetimes are used exactly as given, in the broker's server time; timezone-aware ones are converted to
+        it. The default window is computed on the server's clock.
+        """
+        self._require_connected()
+        now = self.server_time or datetime.now(timezone.utc).replace(tzinfo=None)
+        end = self._server_naive(end)
+        start = self._server_naive(start)
+        if end is None:
+            end = now + timedelta(days=1)            # nothing the server has booked is later than this
+        if start is None:
+            start = now - timedelta(days=30)
+        ms = int(timeout * 1000) if timeout is not None else int(self._api.DownloadOrderHistoryTimeoutMs)
+        return History._from_core(self._api.DownloadOrderHistory(to_core_time(start), to_core_time(end), ms))
+
+    @translated
+    def deal_history(self, year: int, month: int) -> History:
+        """One calendar month of history (a convenience over :meth:`history`)."""
+        self._require_connected()
+        return History._from_core(self._api.RequestDealHistory(int(year), int(month)))
+
+    @translated
+    def request_history(self, start: datetime, end: datetime) -> None:
+        """Ask for history without waiting; it arrives through :meth:`on_history`. The server's answer is not trimmed
+        to ``start`` / ``end`` (it can hold more than you asked for, in pages): filter by time. The blocking
+        :meth:`history` does trim."""
+        self._require_connected()
+        self._api.RequestOrderHistory(to_core_time(self._server_naive(start)), to_core_time(self._server_naive(end)))
+
+    @translated
+    def request_history_month(self, year: int, month: int) -> None:
+        """Ask for one calendar month of history without waiting; it arrives through :meth:`on_history`."""
+        self._require_connected()
+        self._api.RequestOrderHistory(int(year), int(month))
+
+    # ---- realized figures and curves ---------------------------------------------------------------------------
+
+    @translated
+    def summary(self, start: Optional[datetime] = None, end: Optional[datetime] = None) -> AccountSummary:
+        """Realized trading result, deposits and withdrawals, from the deal ledger (all time by default).
+
+        Downloads the deal history, so it blocks; call it off your UI thread (or use ``asyncio.to_thread``).
+        """
+        self._require_connected()
+        if start is None and end is None:
+            return AccountSummary._from_core(self._api.GetAccountSummary())
+        if start is None or end is None:
+            raise ValueError("give both start and end, or neither")
+        return AccountSummary._from_core(self._api.GetAccountSummary(to_core_time(self._server_naive(start)),
+                                                                     to_core_time(self._server_naive(end))))
+
+    @translated
+    def equity_history(self, start: datetime, timeframe: str = "D1", exclude_same_bars: bool = True) -> List[EquityPoint]:
+        """The balance and equity curve since ``start`` (``timeframe`` is ``H1``, ``H4`` or ``D1``).
+
+        ``balance`` is exact; the historical ``equity`` is a bar-priced reconstruction and a point with
+        ``incomplete`` set has understated floating P/L. With ``exclude_same_bars`` (the default, as in the C# library)
+        consecutive points with an unchanged balance and equity are dropped. Downloads deals and per-symbol bars, so it
+        blocks.
+        """
+        self._require_connected()
+        tf = enum_value(self._core.EquityTimeframe, timeframe, "equity timeframe")
+        points = self._api.CalculateEquityHistory(to_core_time(self._server_naive(start)), tf, bool(exclude_same_bars))
+        return [EquityPoint._from_core(p) for p in (points or ())]

pmt5api/_base.py

@@ -0,0 +1,24 @@
+"""What every client mixin may rely on: the core object, the core's namespace, and the connection guard."""
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Any, Optional
+
+from .errors import NotConnectedError
+
+
+class _Base:
+    _api: Any      # the core's client object (MT5API / MT4API)
+    _core: Any     # the core's namespace (types and enums)
+
+    def _require_connected(self) -> None:
+        if not self._api.Connected:
+            raise NotConnectedError("not connected; call connect() first")
+
+    def _server_naive(self, value: Optional[datetime]) -> Optional[datetime]:
+        """A datetime as the naive server time the core works in. A naive value is taken to be server time already
+        (as documented); a timezone-aware one is converted: to UTC, then by the server's offset from UTC."""
+        if value is None or value.tzinfo is None:
+            return value
+        offset = getattr(self, "server_utc_offset", None) or timedelta(0)
+        return value.astimezone(timezone.utc).replace(tzinfo=None) + offset

pmt5api/_coverage.py

@@ -0,0 +1,216 @@
+"""Where every public member and type of the C# SDK went.
+
+``COVERAGE`` maps each public member name of ``MT5API`` to the Python name that provides it:
+
+* ``"Client.<attr>"``       a method, property or constructor argument of :class:`pmt5api.Client`
+* ``"Client(<argument>)"``  an argument of the constructor
+* ``"pmt5api.<name>"``      a module-level function
+* ``"not applicable: …"``   deliberately has no Python counterpart, with the reason
+
+``TYPES`` does the same for the public types. The integration test ``test_coverage`` reflects the DLL it is pointed at
+and fails when a public member or type has no entry here, or when an entry names a Python attribute that does not
+exist. A new SDK release therefore cannot add API without a decision being recorded.
+"""
+from __future__ import annotations
+
+from typing import Dict
+
+COVERAGE: Dict[str, str] = {
+    # ---- lifecycle and session ----
+    "Connect": "Client.connect",
+    "Disconnect": "Client.disconnect",
+    "Connected": "Client.connected",
+    "ConnectTime": "Client.connect_time",
+    "LastQuoteTime": "Client.last_quote_time",
+    "LastServerMessageTime": "Client.last_server_message_time",
+    "ServerTime": "Client.server_time",
+    "ServerTimeZoneInMinutes": "Client.server_utc_offset",
+    "ServerTradeBuild": "Client.trade_build",
+    "ServerSymBuild": "Client.symbol_build",
+    "AccountCompanyName": "Client.company",
+    "AccountMethod": "Client.account_method",
+    "IsInvestor": "Client.is_investor",
+    "IsTradeAllowed": "Client.can_trade",
+    "IsTradeDisableOnServer": "Client.trading_disabled_by_server",
+    "IsNotConfirmedAccount": "Client.is_confirmed",
+    "User": "Client.login",
+    "Password": "Client(password)",
+    "Host": "Client.host",
+    "Server": "Client.host",
+    "Port": "Client.port",
+    "Id": "not applicable: a free-form tag for the caller's own use; keep it in your own code",
+    "ProcessServerMessagesInThread": "not applicable: documented by the core as reserved and unused",
+    "AuthTagsSeen": "not applicable: protocol diagnostics for the ops sentinel, of no use to an application",
+    "AuthUnknownTags": "not applicable: protocol diagnostics for the ops sentinel, of no use to an application",
+    "ChangePassword": "Client.change_password",
+    # ---- configuration ----
+    "ApiKey": "Client(api_key)",
+    "TokenServiceUrl": "Client(token_url)",
+    "TokenServiceTimeout": "Client(token_timeout)",
+    "ConnectTimeout": "Client(connect_timeout)",
+    "ClusterMemberConnectTimeout": "Client(cluster_member_timeout)",
+    "ExecutionTimeout": "Client(execution_timeout)",
+    "GetQuoteTimeoutMs": "Client(quote_timeout)",
+    "DownloadOrderHistoryTimeoutMs": "Client(history_timeout)",
+    "DownloadQuoteHistoryTimeout": "Client(bars_timeout)",
+    "PingTime": "Client(ping_interval)",
+    "NoServerMessagesTimeout": "Client(no_message_timeout)",
+    "ProcessEventTimeoutMs": "not applicable: the core accepts the value but never applies it (events run on the thread pool); "
+                             "pmt5api delivers events through one queued dispatcher instead — see Client.events_dropped",
+    "AutoReconnect": "Client(auto_reconnect)",
+    "ReconnectBackoffMs": "Client(reconnect_backoff)",
+    "ReconnectMaxBackoffMs": "Client(reconnect_max_backoff)",
+    "ReconnectMaxAttempts": "Client(reconnect_max_attempts)",
+    "ProxyEnable": "Client(proxy)",
+    "ProxyType": "Client(proxy)",
+    "ProxyHost": "Client(proxy)",
+    "ProxyPort": "Client(proxy)",
+    "ProxyUser": "Client(proxy)",
+    "ProxyPassword": "Client(proxy)",
+    "PfxFile": "Client(certificate)",
+    "PfxFilePassword": "Client(certificate_password)",
+    "CommonKey": "Client(common_key)",
+    "PlacedType": "Client(placed_type)",
+    "EnableAllOrderUpdates": "Client(all_order_updates)",
+    # ---- symbols and market data ----
+    "Symbols": "Client.symbols",
+    "Subscribe": "Client.subscribe",
+    "Unsubscribe": "Client.unsubscribe",
+    "Subscriptions": "Client.subscriptions",
+    "IsSubscribed": "Client.is_subscribed",
+    "IsQuoteSession": "Client.is_quote_session",
+    "IsTradeSession": "Client.is_trade_session",
+    "GetQuote": "Client.quote",
+    "GetQuoteTask": "Client.aquote",
+    "GetTickValue": "Client.tick_value",
+    "GetAskTickValue": "Client.tick_value",
+    "GetBidTickValue": "Client.tick_value",
+    "GetContractSize": "Client.contract_size",
+    "LedgerValuePerUnitLot": "Client.ledger_value_per_lot",
+    "DownloadQuoteHistoryToday": "Client.bars",
+    "DownloadQuoteHistoryMonth": "Client.bars",
+    "RequestQuoteHistoryToday": "Client.request_bars",
+    "RequestQuoteHistoryMonth": "Client.request_bars",
+    "ConvertToTimeframe": "pmt5api.aggregate",
+    # ---- account ----
+    "Account": "Client.account",
+    "AccountCurrency": "Client.account",
+    "AccountEquity": "Client.account",
+    "AccountProfit": "Client.account",
+    "AccountFloatingProfit": "Client.account",
+    "AccountSwap": "Client.account",
+    "AccountCommission": "Client.account",
+    "AccountFee": "Client.account",
+    "AccountMargin": "Client.account",
+    "AccountFreeMargin": "Client.account",
+    "AccountMarginLevel": "Client.account",
+    "UpdateProfits": "Client.update_profits",
+    "GetOpenedOrders": "Client.orders",
+    "ClosedOrders": "Client.closed_orders",
+    "DownloadOrderHistory": "Client.history",
+    "RequestDealHistory": "Client.deal_history",
+    "RequestOrderHistory": "Client.request_history",
+    "GetAccountSummary": "Client.summary",
+    "CalculateEquityHistory": "Client.equity_history",
+    # ---- sizing and risk ----
+    "CalibrateMoneyScale": "Client.calibrate_money_scale",
+    "MoneyScale": "Client.money_scale",
+    "MoneyScaleEvidence": "Client.money_scale_evidence",
+    "MoneyScaleFromDeal": "Client.money_scale_from_deal",
+    "CalculateLots": "Client.lots_for_risk",
+    "RequiredMargin": "Client.required_margin",
+    "CalculateOrderProfit": "Client.order_profit",
+    "ComputeTickValueFromDeal": "pmt5api.tick_value_from_deal",
+    # ---- trading ----
+    "OrderSend": "Client.buy",
+    "OrderModify": "Client.modify",
+    "OrderClose": "Client.close",
+    "OrderCancel": "Client.cancel",
+    "OrderSendAsync": "Client.buy_async",
+    "OrderModifyAsync": "Client.modify_async",
+    "OrderCloseAsync": "Client.close_async",
+    "OrderCancelAsync": "Client.cancel_async",
+    "OrderSendAsyncTask": "Client.abuy",
+    "OrderModifyAsyncTask": "Client.amodify",
+    "OrderCloseAsyncTask": "Client.aclose",
+    "OrderCancelAsyncTask": "Client.acancel",
+    "GetRequestId": "Client.new_request_id",
+    # ---- events ----
+    "OnQuote": "Client.on_quote",
+    "OnOrderUpdate": "Client.on_order_update",
+    "OnOrderProgress": "Client.on_order_progress",
+    "OnConnectProgress": "Client.on_connect_progress",
+    "OnOrderHistory": "Client.on_history",
+    "OnQuoteHistory": "Client.on_quote_history",
+    "OnSymbolsUpdate": "Client.on_symbols_update",
+    "OnSymbolUpdate": "Client.on_symbol_update",
+    # ---- offline and administration ----
+    "LoadServersDat": "pmt5api.load_servers_dat",
+    "SaveServersDat": "pmt5api.save_servers_dat",
+    "RequestDemoAccount": "pmt5api.request_demo_account",
+}
+
+TYPES: Dict[str, str] = {
+    "MT5API": "pmt5api.Client",
+    "Account": "pmt5api.AccountInfo",
+    "AccountAnswer": "pmt5api.DemoAccount",
+    "AccountRequest": "pmt5api.DemoAccountRequest",
+    "AccountSummary": "pmt5api.AccountSummary",
+    "Bar": "pmt5api.Bar",
+    "Comission": "pmt5api.CommissionTier",
+    "ComissionInfo": "pmt5api.CommissionInfo",
+    "ConnectEventArgs": "pmt5api.ConnectEvent",
+    "ConnectException": "pmt5api.ConnectError",
+    "ConnectionException": "pmt5api.ConnectionLostError",
+    "Deal": "pmt5api.Deal",
+    "Diag": "pmt5api.enable_core_logging",
+    "EquityPoint": "pmt5api.EquityPoint",
+    "Expiration": "Client.place_order(expiration)",
+    "FromBufReader": "not applicable: a protocol buffer reader; it carries no application meaning",
+    "InvestorModeException": "pmt5api.InvestorModeError",
+    "LicenseException": "pmt5api.LicenseError",
+    "Logger": "pmt5api.enable_core_logging",
+    "Logger+OnMsgHandler": "pmt5api.enable_core_logging",
+    "Logger+OnMsgHandlerEx": "pmt5api.enable_core_logging",
+    "LotSizing": "pmt5api.LotSizing",
+    "OnConnectProgress": "Client.on_connect_progress",
+    "OnOrderHistory": "Client.on_history",
+    "OnOrderProgress": "Client.on_order_progress",
+    "OnOrderUpdate": "Client.on_order_update",
+    "OnQuote": "Client.on_quote",
+    "OnQuoteHistory": "Client.on_quote_history",
+    "OnSymbolUpdate": "Client.on_symbol_update",
+    "OnSymbolsUpdate": "Client.on_symbols_update",
+    "Order": "pmt5api.Order",
+    "OrderHistoryEventArgs": "pmt5api.History",
+    "OrderProgress": "pmt5api.OrderProgress",
+    "OrderProgressEventArgs": "not applicable: superseded by OrderProgress, which carries the request, the result and the update",
+    "OrderUpdate": "pmt5api.OrderUpdate",
+    "ProxyException": "pmt5api.ProxyError",
+    "ProxySocket": "not applicable: the transport the core uses for a proxy; configure it with Client(proxy=Proxy(...))",
+    "Quote": "pmt5api.Quote",
+    "QuoteHistoryEventArgs": "pmt5api.QuoteHistoryEvent",
+    "ServerException": "pmt5api.ServerError",
+    "ServerRecord": "pmt5api.ServerRecord",
+    "Session": "pmt5api.TradingSession",
+    "SymBaseInfo": "pmt5api.BaseInfo",
+    "SymGroup": "pmt5api.SymbolInfo",
+    "SymbolInfo": "pmt5api.SymbolInfo",
+    "SymbolSessions": "pmt5api.SymbolSessions",
+    "SymbolUpdate": "Client.on_symbol_update",
+    "Symbols": "Client.symbols",
+    "TokenServiceException": "pmt5api.TokenServiceError",
+    "TradeRequest": "pmt5api.OrderProgress",
+    "TradeResult": "pmt5api.OrderProgress",
+    "TransactionInfo": "pmt5api.OrderUpdate",
+    # enums are exposed as their member names (strings)
+    "AccMethod": "enum: str", "CalculationMode": "enum: str", "CommissionPeriod": "enum: str",
+    "CommissionType": "enum: str", "ConnectProgress": "enum: str", "DealType": "enum: str", "Direction": "enum: str",
+    "EquityTimeframe": "enum: str", "ExecutionType": "enum: str", "ExpirationType": "enum: str",
+    "FillPolicy": "enum: str", "GTCMode": "enum: str", "InstantCommissionType": "enum: str",
+    "LicenseReason": "enum: str", "Logger+MsgType": "enum: str", "MarginMode": "enum: str", "Msg": "enum: str",
+    "OrderState": "enum: str", "OrderType": "enum: str", "PlacedType": "enum: str", "ProgressType": "enum: str",
+    "ProxyTypes": "enum: str", "SwapType": "enum: str", "TradeMode": "enum: str", "TradeType": "enum: str",
+    "UpdateType": "enum: str", "V3DaysSwap": "enum: str", "vCommissionUnitMode": "enum: str",
+    "vCommissionUnitType": "enum: str",
+}

pmt5api/_events.py

@@ -0,0 +1,147 @@
+"""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 translate
+from .models import ConnectEvent, History, OrderProgress, OrderUpdate, Quote
+
+log = logging.getLogger("pmt5api")
+
+
+class _EventsMixin(_Base):
+    def _add_handler(self, event: str, handler: Any) -> None:
+        ev = getattr(self._api, event)
+        ev += handler
+        setattr(self._api, event, ev)
+
+    def _remove_handler(self, event: str, handler: Any) -> None:
+        ev = getattr(self._api, event)
+        ev -= handler
+        setattr(self._api, event, ev)
+
+    def _dispatcher(self) -> _Dispatcher:
+        with self._lock:
+            d = getattr(self, "_dispatch", None)
+            if d is None:
+                d = self._dispatch = _Dispatcher()
+            return d
+
+    @property
+    def events_dropped(self) -> int:
+        """How many events were dropped because callbacks fell too far behind (see the module notes)."""
+        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(handler)
+
+        def remove() -> None:
+            active["on"] = False
+            with self._lock:
+                if handler in self._handlers:
+                    self._handlers.remove(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, filled,
+        modified, closed, stopped out ...). Set ``all_order_updates=True`` on the client to also receive the
+        intermediate Started / Filled / Cancelling states."""
+        return self._watch("OnOrderUpdate", OrderUpdate._from_core, callback)
+
+    def on_order_progress(self, callback: Callable[[OrderProgress], None]) -> Callable[[], None]:
+        """Call ``callback(progress)`` as an asynchronous trade request advances (see :meth:`buy_async`)."""
+        return self._watch("OnOrderProgress", OrderProgress._from_core, callback)
+
+    def on_connect_progress(self, callback: Callable[[ConnectEvent], None]) -> Callable[[], None]:
+        """Call ``callback(event)`` for each connect step and for a drop. This is how to tell a permanent failure from
+        a transient one while ``auto_reconnect`` is on."""
+        def convert(args: Any) -> ConnectEvent:
+            err = args.Exception
+            mapped = translate(err) if err is not None else None
+            return ConnectEvent(stage=str(args.Progress), error=mapped if mapped is not None else err)
+        return self._watch("OnConnectProgress", convert, callback)
+
+    def on_history(self, callback: Callable[[History], None]) -> Callable[[], None]:
+        """Call ``callback(history)`` when history requested with :meth:`request_history` arrives. The server may
+        deliver it in pages (``history.more`` says another page follows) and does not trim it to the range you asked
+        for: filter by time."""
+        return self._watch("OnOrderHistory", History._from_core, callback)
+
+    def on_quote_history(self, callback: Callable[[QuoteHistoryEvent], None]) -> Callable[[], None]:
+        """Call ``callback(event)`` when bars requested with :meth:`request_bars` arrive."""
+        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:`symbols` again."""
+        return self._watch("OnSymbolsUpdate", None, callback)
+
+    def on_symbol_update(self, callback: Callable[[], None]) -> Callable[[], None]:
+        """Call ``callback()`` when one symbol's data is (re)received; read :meth:`symbols` again."""
+        return self._watch("OnSymbolUpdate", 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 = {s for g in symbols for s in ([g] if isinstance(g, str) else g)}
+        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 = {s for g in symbols for s in ([g] if isinstance(g, str) else g)}
+        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]