pmt5api 1.0.0__py3-none-any.whl

pmt5api/docs/FROM-CSHARP.md

@@ -0,0 +1,131 @@
+# From C# to Python
+
+Every public member of the C# `MT5API` class and where it went. Generated from `pmt5api.COVERAGE`, which an integration test checks against the DLL: a new C# member cannot ship without an entry here.
+
+| C# member | Python |
+|---|---|
+| `Account` | `Client.account` |
+| `AccountCommission` | `Client.account` |
+| `AccountCompanyName` | `Client.company` |
+| `AccountCurrency` | `Client.account` |
+| `AccountEquity` | `Client.account` |
+| `AccountFee` | `Client.account` |
+| `AccountFloatingProfit` | `Client.account` |
+| `AccountFreeMargin` | `Client.account` |
+| `AccountMargin` | `Client.account` |
+| `AccountMarginLevel` | `Client.account` |
+| `AccountMethod` | `Client.account_method` |
+| `AccountProfit` | `Client.account` |
+| `AccountSwap` | `Client.account` |
+| `ApiKey` | `Client(api_key)` |
+| `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 |
+| `AutoReconnect` | `Client(auto_reconnect)` |
+| `CalculateEquityHistory` | `Client.equity_history` |
+| `CalculateLots` | `Client.lots_for_risk` |
+| `CalculateOrderProfit` | `Client.order_profit` |
+| `CalibrateMoneyScale` | `Client.calibrate_money_scale` |
+| `ChangePassword` | `Client.change_password` |
+| `ClosedOrders` | `Client.closed_orders` |
+| `ClusterMemberConnectTimeout` | `Client(cluster_member_timeout)` |
+| `CommonKey` | `Client(common_key)` |
+| `ComputeTickValueFromDeal` | `pmt5api.tick_value_from_deal` |
+| `Connect` | `Client.connect` |
+| `Connected` | `Client.connected` |
+| `ConnectTime` | `Client.connect_time` |
+| `ConnectTimeout` | `Client(connect_timeout)` |
+| `ConvertToTimeframe` | `pmt5api.aggregate` |
+| `Disconnect` | `Client.disconnect` |
+| `DownloadOrderHistory` | `Client.history` |
+| `DownloadOrderHistoryTimeoutMs` | `Client(history_timeout)` |
+| `DownloadQuoteHistoryMonth` | `Client.bars` |
+| `DownloadQuoteHistoryTimeout` | `Client(bars_timeout)` |
+| `DownloadQuoteHistoryToday` | `Client.bars` |
+| `EnableAllOrderUpdates` | `Client(all_order_updates)` |
+| `ExecutionTimeout` | `Client(execution_timeout)` |
+| `GetAccountSummary` | `Client.summary` |
+| `GetAskTickValue` | `Client.tick_value` |
+| `GetBidTickValue` | `Client.tick_value` |
+| `GetContractSize` | `Client.contract_size` |
+| `GetOpenedOrders` | `Client.orders` |
+| `GetQuote` | `Client.quote` |
+| `GetQuoteTask` | `Client.aquote` |
+| `GetQuoteTimeoutMs` | `Client(quote_timeout)` |
+| `GetRequestId` | `Client.new_request_id` |
+| `GetTickValue` | `Client.tick_value` |
+| `Host` | `Client.host` |
+| `Id` | not applicable: a free-form tag for the caller's own use; keep it in your own code |
+| `IsInvestor` | `Client.is_investor` |
+| `IsNotConfirmedAccount` | `Client.is_confirmed` |
+| `IsQuoteSession` | `Client.is_quote_session` |
+| `IsSubscribed` | `Client.is_subscribed` |
+| `IsTradeAllowed` | `Client.can_trade` |
+| `IsTradeDisableOnServer` | `Client.trading_disabled_by_server` |
+| `IsTradeSession` | `Client.is_trade_session` |
+| `LastQuoteTime` | `Client.last_quote_time` |
+| `LastServerMessageTime` | `Client.last_server_message_time` |
+| `LedgerValuePerUnitLot` | `Client.ledger_value_per_lot` |
+| `LoadServersDat` | `pmt5api.load_servers_dat` |
+| `MoneyScale` | `Client.money_scale` |
+| `MoneyScaleEvidence` | `Client.money_scale_evidence` |
+| `MoneyScaleFromDeal` | `Client.money_scale_from_deal` |
+| `NoServerMessagesTimeout` | `Client(no_message_timeout)` |
+| `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` |
+| `OnSymbolsUpdate` | `Client.on_symbols_update` |
+| `OnSymbolUpdate` | `Client.on_symbol_update` |
+| `OrderCancel` | `Client.cancel` |
+| `OrderCancelAsync` | `Client.cancel_async` |
+| `OrderCancelAsyncTask` | `Client.acancel` |
+| `OrderClose` | `Client.close` |
+| `OrderCloseAsync` | `Client.close_async` |
+| `OrderCloseAsyncTask` | `Client.aclose` |
+| `OrderModify` | `Client.modify` |
+| `OrderModifyAsync` | `Client.modify_async` |
+| `OrderModifyAsyncTask` | `Client.amodify` |
+| `OrderSend` | `Client.buy` |
+| `OrderSendAsync` | `Client.buy_async` |
+| `OrderSendAsyncTask` | `Client.abuy` |
+| `Password` | `Client(password)` |
+| `PfxFile` | `Client(certificate)` |
+| `PfxFilePassword` | `Client(certificate_password)` |
+| `PingTime` | `Client(ping_interval)` |
+| `PlacedType` | `Client(placed_type)` |
+| `Port` | `Client.port` |
+| `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 |
+| `ProcessServerMessagesInThread` | not applicable: documented by the core as reserved and unused |
+| `ProxyEnable` | `Client(proxy)` |
+| `ProxyHost` | `Client(proxy)` |
+| `ProxyPassword` | `Client(proxy)` |
+| `ProxyPort` | `Client(proxy)` |
+| `ProxyType` | `Client(proxy)` |
+| `ProxyUser` | `Client(proxy)` |
+| `ReconnectBackoffMs` | `Client(reconnect_backoff)` |
+| `ReconnectMaxAttempts` | `Client(reconnect_max_attempts)` |
+| `ReconnectMaxBackoffMs` | `Client(reconnect_max_backoff)` |
+| `RequestDealHistory` | `Client.deal_history` |
+| `RequestDemoAccount` | `pmt5api.request_demo_account` |
+| `RequestOrderHistory` | `Client.request_history` |
+| `RequestQuoteHistoryMonth` | `Client.request_bars` |
+| `RequestQuoteHistoryToday` | `Client.request_bars` |
+| `RequiredMargin` | `Client.required_margin` |
+| `SaveServersDat` | `pmt5api.save_servers_dat` |
+| `Server` | `Client.host` |
+| `ServerSymBuild` | `Client.symbol_build` |
+| `ServerTime` | `Client.server_time` |
+| `ServerTimeZoneInMinutes` | `Client.server_utc_offset` |
+| `ServerTradeBuild` | `Client.trade_build` |
+| `Subscribe` | `Client.subscribe` |
+| `Subscriptions` | `Client.subscriptions` |
+| `Symbols` | `Client.symbols` |
+| `TokenServiceTimeout` | `Client(token_timeout)` |
+| `TokenServiceUrl` | `Client(token_url)` |
+| `Unsubscribe` | `Client.unsubscribe` |
+| `UpdateProfits` | `Client.update_profits` |
+| `User` | `Client.login` |
+
+Enumerations are exposed as their member names (strings): `order.order_type == "Buy"`.

pmt5api/errors.py

@@ -0,0 +1,150 @@
+"""Exceptions raised by pmt5api.
+
+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 Optional
+
+
+class WmtError(Exception):
+    """Base class of every pmt5api error."""
+
+
+class CoreNotFoundError(WmtError):
+    """The licensed core library (wmt5api.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.
+    """
+
+    def __init__(self, message: str, reason: str = "Unknown"):
+        super().__init__(message)
+        self.reason = reason
+
+
+class TokenServiceError(WmtError):
+    """The licence service could not be reached or answered with something unusable (not a licence decision)."""
+
+
+class ConnectError(WmtError):
+    """The broker's access server could not be reached."""
+
+
+class NotConnectedError(WmtError):
+    """The call needs a connection and the client is not connected."""
+
+
+class ConnectionLostError(WmtError):
+    """An established connection was lost."""
+
+
+class ServerError(WmtError):
+    """The broker's server refused the request (for example an incorrect login or password, or a rejected order).
+
+    ``code`` is the server's return code by name (``"REQUOTE"``, ``"NO_MONEY"``, ``"INVALID_PRICE"``, ...) and
+    ``code_value`` its number; 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 InvestorModeError(ServerError):
+    """The account was opened with an investor (read-only) password and the request needs trading rights."""
+
+
+class ProxyError(WmtError):
+    """The configured proxy refused or failed."""
+
+
+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 InvalidRequestError(WmtError, ValueError):
+    """The request was rejected before it was sent (for example, a symbol the server does not know)."""
+
+
+_BY_NAME = {
+    "LicenseException": LicenseError,
+    "TokenServiceException": TokenServiceError,
+    "ConnectException": ConnectError,
+    "ConnectionException": ConnectError,          # proxy handshake or client-certificate failure while connecting
+    "InvestorModeException": InvestorModeError,
+    "ServerException": ServerError,
+    "ProxyException": ProxyError,
+    "TimeoutException": RequestTimeout,
+    "ArgumentException": InvalidRequestError,
+    "SocketException": ConnectError,
+}
+
+# The core raises a few conditions as a bare System.Exception whose message is the only thing that identifies them.
+_BARE_MESSAGES = (
+    ("Not connected", NotConnectedError),
+    ("Previous request still running", BusyError),
+    ("Download Order History Running", BusyError),
+    ("Cannot DownloadQuoteHistory", RequestTimeout),
+    ("Request Lots = 0", InvalidRequestError),
+)
+
+# Wrappers the runtime puts around the exception that matters (a failed task, a reflected call).
+_WRAPPERS = ("AggregateException", "TargetInvocationException")
+
+
+def translate(exc: BaseException) -> Optional[WmtError]:
+    """Return the pmt5api 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__:
+        cls = _BY_NAME.get(klass.__name__)
+        if cls is None:
+            continue
+        message = str(getattr(exc, "Message", None) or exc)
+        if cls is LicenseError:
+            reason = getattr(exc, "Reason", None)
+            return LicenseError(message, str(reason) if reason is not None else "Unknown")
+        if issubclass(cls, ServerError):
+            code = getattr(exc, "Code", None)
+            try:
+                value = int(code) if code is not None else None
+            except (TypeError, ValueError):
+                value = None
+            return cls(message, str(code) if code is not None else None, value)
+        if cls is ConnectError and message.startswith("Disconnected"):
+            return ConnectionLostError(message)
+        return cls(message)
+    if type(exc).__name__ == "Exception" and getattr(type(exc), "__module__", "") == "System":
+        text = str(getattr(exc, "Message", None) or exc)
+        for prefix, cls in _BARE_MESSAGES:
+            if text.startswith(prefix):
+                return cls(text)
+    return None

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