pmt5api 1.0.0__py3-none-any.whl

pmt5api/client.py

@@ -0,0 +1,129 @@
+"""The Python client: a typed, translated layer over every public capability of the licensed wmt5api core.
+
+The class is assembled from topic mixins (session, market data, account, risk, trading, events). Everything the C#
+SDK offers is reachable here by a Pythonic name; ``pmt5api.COVERAGE`` lists, member by member, where each C# member
+went, and a test fails when the core gains a member that has no entry.
+"""
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass
+from typing import Any, List, Optional
+
+from . import _runtime
+from ._account import _AccountMixin
+from ._events import _EventsMixin
+from ._market import _MarketMixin
+from ._risk import _RiskMixin
+from ._session import _SessionMixin
+from ._trading import _TradingMixin
+from ._util import enum_value, placed_type as _placed, seconds_to_ms
+
+
+@dataclass(frozen=True)
+class Proxy:
+    """A proxy the core connects through. ``kind`` is ``"https"``, ``"socks4"`` or ``"socks5"``."""
+    kind: str
+    host: str
+    port: int
+    user: Optional[str] = None
+    password: Optional[str] = None
+
+
+class Client(_SessionMixin, _MarketMixin, _AccountMixin, _RiskMixin, _TradingMixin, _EventsMixin):
+    """A connection to one MetaTrader 5 account through the licensed core.
+
+    >>> with Client(login, password, host, port, api_key="wk_...") as c:
+    ...     print(c.quote("EURUSD"))
+
+    Credentials and library: ``api_key`` falls back to the ``WMTAPI_KEY`` environment variable and ``token_url`` to
+    ``WMTAPI_TOKEN_URL`` (the core reads both itself); ``dll_path`` falls back to ``WMTAPI_DLL``, then to the core
+    bundled in the wheel.
+
+    Timeouts are in seconds: ``connect_timeout`` (one connect attempt on one server), ``cluster_member_timeout`` (the
+    per-server limit while failing over across the broker's cluster), ``token_timeout`` (each licence request), ``execution_timeout`` (a trade confirmation),
+    ``quote_timeout`` (waiting for a quote), ``history_timeout`` / ``bars_timeout`` (downloads), ``ping_interval``
+    (keepalive), ``no_message_timeout`` (silence after which ``connected`` turns false). Every timeout must be
+    positive; the quote, history and bars timeouts are the defaults of :meth:`quote`, :meth:`history` and :meth:`bars`.
+
+    Reconnecting: ``auto_reconnect=True`` turns on the core's watchdog (exponential backoff with jitter, failover to the
+    broker's cluster members, re-subscription); tune it with ``reconnect_backoff`` / ``reconnect_max_backoff`` (seconds)
+    and ``reconnect_max_attempts`` (0 = until reconnected or ``disconnect()``). Do not poll ``connected`` and call
+    ``connect()`` in a loop.
+
+    ``proxy`` routes the connection through a :class:`Proxy`. ``certificate`` / ``certificate_password`` are for brokers
+    that require a client certificate (the bytes of a ``.pfx`` file); ``common_key`` (15 bytes) is for servers that
+    require one. ``placed_type`` records how orders are placed (``"manual"``
+    or ``"expert"``; a per-call ``placed_type="manual"`` equals the default and so takes the client's value). ``all_order_updates=True`` also delivers the intermediate order states to
+    :meth:`on_order_update`.
+
+    Callbacks run on the core's worker threads, not on the thread that created the client.
+    """
+
+    def __init__(self, login: int, password: str, host: str, port: int = 443, *,
+                 api_key: Optional[str] = None, token_url: Optional[str] = None, dll_path: Optional[str] = None,
+                 connect_timeout: Optional[float] = None, cluster_member_timeout: Optional[float] = None,
+                 token_timeout: Optional[float] = None, execution_timeout: Optional[float] = None,
+                 quote_timeout: Optional[float] = None, history_timeout: Optional[float] = None,
+                 bars_timeout: Optional[float] = None, ping_interval: Optional[float] = None,
+                 no_message_timeout: Optional[float] = None,
+                 auto_reconnect: bool = False, reconnect_backoff: Optional[float] = None,
+                 reconnect_max_backoff: Optional[float] = None, reconnect_max_attempts: Optional[int] = None,
+                 proxy: Optional[Proxy] = None, certificate: Optional[bytes] = None,
+                 certificate_password: Optional[str] = None, common_key: Optional[bytes] = None,
+                 placed_type: Optional[str] = None, all_order_updates: bool = False):
+        core = _runtime.load(dll_path)
+        self._core = core
+        self._login = int(login)
+        self._host = host
+        self._port = int(port)
+        self._api = core.MT5API(self._login, password, host, self._port)
+        self._lock = threading.RLock()
+        self._bars_lock = threading.Lock()
+        self._handlers: List[Any] = []
+        api = self._api
+        if api_key:
+            api.ApiKey = api_key
+        if token_url:
+            api.TokenServiceUrl = token_url
+        for attr, value in (("ConnectTimeout", connect_timeout), ("ClusterMemberConnectTimeout", cluster_member_timeout),
+                            ("TokenServiceTimeout", token_timeout), ("ExecutionTimeout", execution_timeout),
+                            ("GetQuoteTimeoutMs", quote_timeout), ("DownloadOrderHistoryTimeoutMs", history_timeout),
+                            ("DownloadQuoteHistoryTimeout", bars_timeout), ("PingTime", ping_interval),
+                            ("NoServerMessagesTimeout", no_message_timeout),
+                            ("ReconnectBackoffMs", reconnect_backoff), ("ReconnectMaxBackoffMs", reconnect_max_backoff)):
+            ms = seconds_to_ms(value, attr)
+            if ms is not None:
+                setattr(api, attr, ms)
+        if reconnect_max_attempts is not None:
+            if int(reconnect_max_attempts) < 0:
+                raise ValueError("reconnect_max_attempts must be 0 (until reconnected) or a positive number")
+            api.ReconnectMaxAttempts = int(reconnect_max_attempts)
+        if auto_reconnect:
+            api.AutoReconnect = True
+        if all_order_updates:
+            api.EnableAllOrderUpdates = True
+        if placed_type:
+            api.PlacedType = _placed(core.PlacedType, placed_type)
+        if proxy is not None:
+            api.ProxyEnable = True
+            api.ProxyType = enum_value(core.ProxyTypes, proxy.kind, "proxy kind")
+            api.ProxyHost = proxy.host
+            api.ProxyPort = int(proxy.port)
+            # the core's proxy handlers refuse null: "no credentials" is the empty string
+            api.ProxyUser = proxy.user or ""
+            api.ProxyPassword = proxy.password or ""
+        if certificate is not None:
+            import System  # noqa: PLC0415
+            api.PfxFile = System.Array[System.Byte](bytes(certificate))
+            if certificate_password is not None:
+                api.PfxFilePassword = certificate_password
+        if common_key is not None:
+            if len(bytes(common_key)) != 15:
+                raise ValueError("common_key must be 15 bytes")
+            import System  # noqa: PLC0415
+            api.CommonKey = System.Array[System.Byte](bytes(common_key))
+
+    def __repr__(self) -> str:
+        return "<pmt5api.Client login=%d host=%s:%d connected=%s>" % (
+            self._login, self._host, self._port, self.connected)

pmt5api/diagnostics.py

@@ -0,0 +1,38 @@
+"""Route the core's own diagnostics into Python's ``logging``."""
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable
+
+from . import _runtime
+
+_LEVELS = {"Trace": logging.DEBUG, "Debug": logging.DEBUG, "Info": logging.INFO, "Warn": logging.WARNING,
+           "Error": logging.ERROR, "Exception": logging.ERROR}
+
+
+def enable_core_logging(logger_name: str = "pmt5api.core") -> Callable[[], None]:
+    """Forward the core's log messages (``Logger.OnMsgEx``) and internal diagnostics (``Diag.Sink``) to the Python
+    logger ``logger_name``. Returns a function that switches it off again. Nothing is forwarded unless this is called,
+    and the core is silent by default."""
+    core = _runtime.load()
+    import System  # noqa: PLC0415
+    logger = logging.getLogger(logger_name)
+
+    def on_msg(sender: Any, msg: Any, kind: Any, ex: Any = None) -> None:
+        level = _LEVELS.get(str(kind), logging.INFO)
+        if logger.isEnabledFor(level):
+            logger.log(level, "%s%s", msg, (" | %s" % ex.Message) if ex is not None else "")
+
+    def on_diag(message: Any) -> None:
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug("%s", message)
+
+    core.Logger.OnMsgEx += on_msg
+    sink = System.Action[System.String](on_diag)
+    previous = core.Diag.Sink
+    core.Diag.Sink = sink
+
+    def disable() -> None:
+        core.Logger.OnMsgEx -= on_msg
+        core.Diag.Sink = previous
+    return disable