pmt4api 1.0.0__py3-none-any.whl

pmt4api/docs/FROM-CSHARP.md

@@ -0,0 +1,151 @@
+# From C# to Python
+
+Every public member of the C# `MT4API` and `OrderClient` classes and where it went. Generated from `pmt4api.COVERAGE`, which an integration test checks against the DLL: a new C# member cannot ship without an entry here.
+
+| C# member | Python | Note |
+|---|---|---|
+| `Account` | `Client.account` |  |
+| `AccountBalance` | `Client.balance` |  |
+| `AccountCredit` | `Client.credit` |  |
+| `AccountEquity` | `Client.equity` |  |
+| `AccountFreeMargin` | `Client.free_margin` |  |
+| `AccountLeverage` | `Client.leverage` |  |
+| `AccountMargin` | `Client.margin` |  |
+| `AccountMarginLevel` | `Client.margin_level` |  |
+| `AccountName` | `Client.account` |  |
+| `AccountProfit` | `Client.profit` |  |
+| `AccountType` | `Client.account` |  |
+| `ApiKey` | `Client(api_key)` |  |
+| `AutoReconnect` | `Client(auto_reconnect)` |  |
+| `CalculateEquityHistory` | `Client.equity_history` |  |
+| `CalculateLots` | `Client.lots_for_risk` |  |
+| `CalculateOrderProfit` | `Client.order_profit` |  |
+| `Connect` | `Client.connect` |  |
+| `Connected` | `Client.connected` |  |
+| `ConnectTimeout` | `Client(connect_timeout)` |  |
+| `Disconnect` | `Client.disconnect` |  |
+| `DownloadOrderHistory` | `Client.history` | `timeout=` and a `threading.Event` for `cancel=` replace the timeout and cancellation token arguments; `ahistory` cancels with the awaiting task |
+| `DownloadOrderHistoryTimeoutMs` | `Client(history_timeout)` |  |
+| `DownloadQuoteHistory` | `Client.bars` | `count=` bars ending at `end`, or everything since `start=`; pages past the wire's 32767-bar limit; the server's own depth limit applies |
+| `DownloadQuoteHistoryTimeout` | `Client(bars_timeout)` |  |
+| `Encoding` | `Client(comment_encoding)` |  |
+| `GetAccountSummary` | `Client.summary` |  |
+| `GetAskTickValue` | `Client.tick_value` |  |
+| `GetBidTickValue` | `Client.tick_value` |  |
+| `GetOpenedOrder` | `Client.order` |  |
+| `GetOpenedOrders` | `Client.orders` |  |
+| `GetQuote` | `Client.quote` |  |
+| `GetQuoteTimeoutMs` | `Client(quote_timeout)` |  |
+| `GetSymbolNames` | `Client.symbols` |  |
+| `GetSymbolSpec` | `Client.symbol` | also `SymbolDigits` and `SymbolExecution`: `SymbolInfo.digits` and `.execution` |
+| `GetTickValue` | `Client.tick_value` | `side='ask'`; `side='bid'` is `GetBidTickValue`. Raises instead of returning NaN |
+| `Groups` | `Client.symbol_groups` |  |
+| `Host` | `Client.host` |  |
+| `IsInvestor` | `Client.is_investor` |  |
+| `IsSubscribed` | `Client.is_subscribed` |  |
+| `LastSrvRecord` | not applicable: the raw wire record the server list was parsed from; read Client.server_list |  |
+| `LiveEquity` | `Client.live_equity` |  |
+| `LiveEquityCached` | `Client.equity` |  |
+| `LiveMarginCached` | `Client.margin` |  |
+| `LoadServersIni` | `pmt4api.load_servers_ini` |  |
+| `NoServerMessagesTimeout` | `Client(no_message_timeout)` |  |
+| `OnConnect` | `Client.on_connect` |  |
+| `OnDisconnect` | `Client.on_disconnect` |  |
+| `OnOrderProgress` | `Client.on_order_progress` |  |
+| `OnOrderUpdate` | `Client.on_order_update` |  |
+| `OnQuote` | `Client.on_quote` |  |
+| `OnQuoteHistory` | `Client.on_quote_history` |  |
+| `OnSymbolsUpdate` | `Client.on_symbols_update` |  |
+| `OrderCancel` | `Client.cancel` |  |
+| `OrderCancelAsync` | `Client.cancel_async` |  |
+| `OrderCancelAsyncTask` | `Client.acancel` |  |
+| `OrderClient` | not applicable: its members (timeout, placement source, progress event, async trading) are reached through Client(trade_timeout), Client(placed_type), Client.on_order_progress and the *_async methods; Client.raw gives the core object |  |
+| `OrderClose` | `Client.close` | partial close with `lots=`; the price defaults to the current bid / ask |
+| `OrderCloseAsync` | `Client.close_async` |  |
+| `OrderCloseAsyncTask` | `Client.aclose` |  |
+| `OrderCloseBy` | `Client.close_by` |  |
+| `OrderCloseByAsync` | `Client.close_by_async` |  |
+| `OrderCloseByAsyncTask` | `Client.aclose_by` |  |
+| `OrderModify` | `Client.modify` | the symbol, type, volume and the values you did not change are taken from the open order, including a pending order's expiration |
+| `OrderModifyAsync` | `Client.modify_async` |  |
+| `OrderModifyAsyncTask` | `Client.amodify` |  |
+| `OrderMultipleCloseBy` | `Client.close_all_by` |  |
+| `OrderMultipleCloseByAsync` | `Client.close_all_by_async` |  |
+| `OrderSend` | `Client.buy` | `buy`, `sell` and `place_order` cover the operations; `magic` other than 0 is refused (the core does not transmit it); the volume must be a multiple of 0.01 |
+| `OrderSendAsync` | `Client.buy_async` | `buy_async`, `sell_async`, `place_order_async`; the integer returned is the request id that `on_order_progress` reports |
+| `OrderSendAsyncTask` | `Client.abuy` |  |
+| `PlacedType` | `Client(placed_type)` |  |
+| `Port` | `Client.port` |  |
+| `Reconnect` | `Client.reconnect` | returns False when every server failed; with `auto_reconnect=True` the core does it by itself |
+| `ReconnectBackoffMs` | `Client(reconnect_backoff)` |  |
+| `ReconnectMaxAttempts` | `Client(reconnect_max_attempts)` |  |
+| `RequiredMargin` | `Client.required_margin` |  |
+| `SaveServersIni` | `pmt4api.save_servers_ini` |  |
+| `Servers` | `Client.servers` | give `servers=[(host, port), ...]` to the constructor or call `add_server` |
+| `ServerTime` | `Client.server_time` |  |
+| `ServerTradeBuild` | `Client.trade_build` |  |
+| `SrvList` | `Client.server_list` |  |
+| `Subscribe` | `Client.subscribe` |  |
+| `SymbolDigits` | `Client.symbol` |  |
+| `SymbolExecution` | `Client.symbol` |  |
+| `TokenServiceTimeout` | `Client(token_timeout)` |  |
+| `TokenServiceUrl` | `Client(token_url)` |  |
+| `TradeTimeout` | `Client(trade_timeout)` |  |
+| `Unsubscribe` | `Client.unsubscribe` |  |
+| `UpdateMargin` | `Client.update_margin` |  |
+| `UpdateProfits` | `Client.update_profits` |  |
+| `User` | `Client.login` |  |
+
+## Types
+
+| C# type | Python |
+|---|---|
+| `AccountInfo` | `pmt4api.AccountInfo` |
+| `AccountSummary` | `pmt4api.AccountSummary` |
+| `AccountType` | enum: str |
+| `Bar` | `pmt4api.Bar` |
+| `ConnectEventArgs` | `pmt4api.ConnectEvent` |
+| `ConnectEventHandler` | not applicable: a .NET delegate type; subscribe with Client.on_connect |
+| `ConnectException` | `pmt4api.ConnectError` |
+| `Diag` | `pmt4api.enable_core_logging` |
+| `DisconnectEventArgs` | `pmt4api.ConnectEvent` |
+| `DisconnectEventHandler` | not applicable: a .NET delegate type; subscribe with Client.on_disconnect |
+| `EquityPoint` | `pmt4api.EquityPoint` |
+| `EquityTimeframe` | enum: str |
+| `ExecutionType` | enum: str |
+| `InvestorModeException` | `pmt4api.InvestorModeError` |
+| `LicenseException` | `pmt4api.LicenseError` |
+| `LicenseReason` | enum: str |
+| `Logger` | `pmt4api.enable_core_logging` |
+| `Logger+MsgType` | enum: str |
+| `Logger+OnMsgHandler` | not applicable: a .NET delegate type; enable_core_logging forwards to Python logging |
+| `Logger+OnMsgHandlerEx` | not applicable: a .NET delegate type; enable_core_logging forwards to Python logging |
+| `LoginRejectedException` | `pmt4api.LoginRejectedError` |
+| `LotSizing` | `pmt4api.LotSizing` |
+| `MT4API` | `pmt4api.Client` |
+| `Mt4Server` | `pmt4api.ServerRecord` |
+| `Order` | `pmt4api.Order` |
+| `OrderClient` | `pmt4api.Client` |
+| `OrderClientAsyncTaskExtensions` | `Client.abuy` |
+| `OrderProgress` | `pmt4api.OrderProgress` |
+| `OrderProgressEventHandler` | not applicable: a .NET delegate type; subscribe with Client.on_order_progress |
+| `OrderType` | enum: str |
+| `OrderUpdate` | `pmt4api.OrderUpdate` |
+| `OrderUpdateEventHandler` | not applicable: a .NET delegate type; subscribe with Client.on_order_update |
+| `PlacedType` | enum: str |
+| `ProgressType` | enum: str |
+| `Quote` | `pmt4api.Quote` |
+| `QuoteEventHandler` | not applicable: a .NET delegate type; subscribe with Client.on_quote |
+| `QuoteHistoryEventArgs` | `pmt4api.QuoteHistoryEvent` |
+| `QuoteHistoryEventHandler` | not applicable: a .NET delegate type; subscribe with Client.on_quote_history |
+| `RequoteException` | `pmt4api.RequoteError` |
+| `ServerException` | `pmt4api.ServerError` |
+| `SymbolSpec` | `pmt4api.SymbolInfo` |
+| `SymbolsUpdateEventHandler` | not applicable: a .NET delegate type; subscribe with Client.on_symbols_update |
+| `SymGroup` | `pmt4api.SymbolGroup` |
+| `Timeframe` | enum: str |
+| `TokenServiceException` | `pmt4api.TokenServiceError` |
+| `TradeTimeoutException` | `pmt4api.RequestTimeout` |
+| `UpdateType` | enum: str |
+
+Enumerations are exposed as their member names (strings): `order.order_type == "Buy"`.

pmt4api/errors.py

@@ -0,0 +1,233 @@
+"""Exceptions raised by pmt4api.
+
+Every error the licensed core raises is translated into one of these, so callers catch a small, stable hierarchy and
+never depend on .NET exception types. The original exception is kept as ``__cause__``.
+"""
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+
+class WmtError(Exception):
+    """Base class of every pmt4api error."""
+
+
+class CoreNotFoundError(WmtError):
+    """The licensed core library (wmt4api.dll) could not be located."""
+
+
+class RuntimeNotFoundError(WmtError):
+    """The .NET runtime needed to host the core could not be started."""
+
+
+class LicenseError(WmtError):
+    """The licence service refused the request.
+
+    ``reason`` is one of: NoKey, Invalid, Expired, Revoked, RateLimited, LoginNotAllowed, AccountLimitReached, Unknown.
+    ``status`` is the service's HTTP status and ``detail`` its own message, for support.
+    """
+
+    def __init__(self, message: str, reason: str = "Unknown", status: Optional[int] = None,
+                 detail: Optional[str] = None):
+        super().__init__(message)
+        self.reason = reason
+        self.status = status
+        self.detail = detail
+
+
+class TokenServiceError(WmtError):
+    """The licence service could not be reached or answered with something unusable (not a licence decision)."""
+
+
+class ConnectError(WmtError):
+    """No access server could be reached (or none answered within ``connect_timeout``)."""
+
+
+class NotConnectedError(WmtError):
+    """The call needs a connection and the client is not connected."""
+
+
+class ConnectionLostError(WmtError):
+    """An established connection was lost, possibly with a request in flight: whether it was applied is unknown;
+    reconnect and look at :meth:`Client.orders` before sending again."""
+
+
+class ProtocolError(WmtError):
+    """The server sent something the core could not decode."""
+
+
+#: The MT4 trade-return codes, by number (the names follow the MetaQuotes error list; the number is authoritative).
+TRADE_CODES: Dict[int, str] = {
+    0: "OK", 1: "NO_RESULT", 2: "COMMON_ERROR", 3: "INVALID_TRADE_PARAMETERS", 4: "SERVER_BUSY", 5: "OLD_VERSION",
+    6: "NO_CONNECTION", 7: "NOT_ENOUGH_RIGHTS", 8: "TOO_FREQUENT_REQUESTS", 9: "MALFUNCTIONAL_TRADE",
+    64: "ACCOUNT_DISABLED", 65: "INVALID_ACCOUNT", 128: "TRADE_TIMEOUT", 129: "INVALID_PRICE", 130: "INVALID_STOPS",
+    131: "INVALID_TRADE_VOLUME", 132: "MARKET_CLOSED", 133: "TRADE_DISABLED", 134: "NOT_ENOUGH_MONEY",
+    135: "PRICE_CHANGED", 136: "OFF_QUOTES", 137: "BROKER_BUSY", 138: "REQUOTE", 139: "ORDER_LOCKED",
+    140: "LONG_POSITIONS_ONLY_ALLOWED", 141: "TOO_MANY_REQUESTS", 145: "MODIFICATION_DENIED",
+    146: "TRADE_CONTEXT_BUSY", 147: "EXPIRATION_DENIED", 148: "TOO_MANY_ORDERS", 149: "HEDGE_PROHIBITED",
+    150: "PROHIBITED_BY_FIFO",
+}
+
+
+def code_name(value: Optional[int]) -> Optional[str]:
+    """The name of an MT4 return code (``None`` for ``None``, ``"CODE_<n>"`` for a number not in the table)."""
+    if value is None:
+        return None
+    return TRADE_CODES.get(int(value), "CODE_%d" % int(value))
+
+
+class ServerError(WmtError):
+    """The broker's server refused the request (a rejected login or a rejected order).
+
+    ``code_value`` is the MT4 return code and ``code`` its name (``"REQUOTE"``, ``"NOT_ENOUGH_MONEY"``,
+    ``"INVALID_STOPS"``, ...); both are ``None`` when the refusal carried no code.
+    """
+
+    def __init__(self, message: str, code: Optional[str] = None, code_value: Optional[int] = None):
+        super().__init__(message)
+        self.code = code
+        self.code_value = code_value
+
+
+class LoginRejectedError(ServerError):
+    """The broker rejected the login: a wrong account number or password (typically code 65), a disabled or expired
+    login, or an authorisation refusal. Fix the credentials; this is not an SDK fault and is not retried across
+    servers."""
+
+
+class RequoteError(ServerError):
+    """An instant-execution price moved before the fill. ``bid`` / ``ask`` are the prices the server now offers:
+    decide again and resend (nothing was filled)."""
+
+    def __init__(self, message: str, bid: float, ask: float, code_value: int = 138):
+        super().__init__(message, code_name(code_value), code_value)
+        self.bid = bid
+        self.ask = ask
+
+
+class InvestorModeError(ServerError):
+    """The account was opened with an investor (read-only) password and the request needs trading rights. Nothing
+    was sent."""
+
+
+class RequestTimeout(WmtError, TimeoutError):
+    """The server did not answer within the requested time.
+
+    For a trade call this means the request WAS sent and was not confirmed in time: the order may have been accepted;
+    look at ``orders()`` before sending again. (When nothing was sent, :class:`NoQuoteError` is raised instead.)
+    """
+
+
+class NoQuoteError(WmtError, TimeoutError):
+    """No quote was available in time to read or to trade against. Nothing was sent."""
+
+
+class BusyError(WmtError):
+    """The core allows one request of this kind at a time and one is still running; wait for it and retry."""
+
+
+class RequestCancelled(WmtError):
+    """The wait was cancelled by the caller (the ``cancel`` event of a download was set)."""
+
+
+class InvalidRequestError(WmtError, ValueError):
+    """The request was rejected before it was sent (for example, a symbol the server does not know)."""
+
+
+_BY_NAME = {
+    "LicenseException": "license",
+    "TokenServiceException": "token",
+    "ConnectException": "connect",
+    "SocketException": "connect",
+    "LoginRejectedException": "login",
+    "RequoteException": "requote",
+    "InvestorModeException": "investor",
+    "ServerException": "server",
+    "TradeTimeoutException": "timeout",
+    "TimeoutException": "timeout",
+    "OperationCanceledException": "cancelled",
+    "ArgumentException": "invalid",
+}
+
+# The core raises a few conditions as a bare System.Exception whose message is the only thing that identifies them.
+_BARE_MESSAGES = (
+    ("MT4 connection closed by server", ConnectionLostError),
+    ("MT4 server closed the session", ConnectionLostError),
+    ("MT4 LZO decompress failed", ProtocolError),
+    ("MT4 pump: unknown opcode", ProtocolError),
+    ("missing '", TokenServiceError),
+    ("malformed '", TokenServiceError),
+)
+
+# Wrappers the runtime puts around the exception that matters (a failed task, a reflected call).
+_WRAPPERS = ("AggregateException", "TargetInvocationException")
+
+
+def _status(text: str) -> Optional[int]:
+    """The number in "... rejected (status N)" of the core's bare connect-phase refusals."""
+    if "(status " not in text:
+        return None
+    try:
+        return int(text.rsplit("(status ", 1)[1].split(")", 1)[0])
+    except ValueError:
+        return None
+
+
+def translate(exc: BaseException) -> Optional[WmtError]:
+    """Return the pmt4api error that corresponds to a core exception, or ``None`` if it is not one of ours.
+
+    Matching is by class name along the exception's inheritance chain (most derived first), so it works without importing
+    the core's types and keeps working if a core exception gains a new base class.
+    """
+    if type(exc).__name__ in _WRAPPERS:
+        inner = getattr(exc, "InnerException", None)
+        if inner is not None:
+            return translate(inner)
+    for klass in type(exc).__mro__:
+        kind = _BY_NAME.get(klass.__name__)
+        if kind is None:
+            continue
+        message = str(getattr(exc, "Message", None) or exc)
+        if kind == "license":
+            reason = getattr(exc, "Reason", None)
+            status = getattr(exc, "HttpStatus", None)
+            detail = getattr(exc, "ServerError", None)
+            return LicenseError(message, str(reason) if reason is not None else "Unknown",
+                                int(status) if status else None, str(detail) if detail else None)
+        if kind == "token":
+            return TokenServiceError(message)
+        if kind == "connect":
+            if "connection lost" in message:
+                return ConnectionLostError(message)
+            return ConnectError(message)
+        if kind in ("login", "server", "requote", "investor"):
+            code = getattr(exc, "Code", None)
+            try:
+                value = int(code) if code is not None else None
+            except (TypeError, ValueError):
+                value = None
+            if kind == "requote":
+                return RequoteError(message, float(exc.Bid), float(exc.Ask), value if value is not None else 138)
+            cls = {"login": LoginRejectedError, "server": ServerError, "investor": InvestorModeError}[kind]
+            return cls(message, code_name(value), value)
+        if kind == "timeout":
+            return RequestTimeout(message)
+        if kind == "cancelled":
+            return RequestCancelled(message)
+        if kind == "invalid":
+            return InvalidRequestError(message)
+    name = type(exc).__name__
+    module = getattr(type(exc), "__module__", "")
+    if name == "Exception" and module == "System":
+        text = str(getattr(exc, "Message", None) or exc)
+        for prefix, cls in _BARE_MESSAGES:
+            if text.startswith(prefix):
+                return cls(text)
+        if text.startswith("MT4 command ") or text.startswith("MT4 cmd-"):
+            value = _status(text)
+            return ServerError(text, code_name(value), value)
+    if name == "InvalidOperationException" and module == "System":
+        text = str(getattr(exc, "Message", None) or exc)
+        if "already in flight" in text:
+            return BusyError(text)
+    return None

pmt4api/frames.py

@@ -0,0 +1,21 @@
+"""Optional pandas helpers (``pip install pandas``)."""
+from __future__ import annotations
+
+import dataclasses
+from typing import Any, Iterable
+
+
+def to_frame(items: Iterable[Any]):
+    """A ``pandas.DataFrame`` from a list of the package's value objects (``Bar``, ``Order``, ``Quote``, ...).
+
+    A list of bars is indexed by its ``time``; anything else keeps a plain integer index.
+    """
+    try:
+        import pandas as pd
+    except ImportError as exc:  # pragma: no cover - depends on the environment
+        raise ImportError("to_frame() needs pandas: pip install pandas") from exc
+    rows = [dataclasses.asdict(x) for x in items]
+    frame = pd.DataFrame(rows)
+    if "time" in frame.columns and {"open", "high", "low", "close"} <= set(frame.columns):
+        frame = frame.set_index("time")
+    return frame