pmt4api 1.0.0__py3-none-any.whl

pmt4api/models.py

@@ -0,0 +1,337 @@
+"""Plain Python value types returned by :class:`pmt4api.Client`.
+
+They are immutable snapshots built from the core's objects, so they can be stored, pickled, compared and handed to other
+threads freely. Times are naive ``datetime`` values in the broker's server time, exactly as the server reports them
+(``None`` when the server leaves the field unset).
+
+Fields are read strictly: if the core ever drops or renames one, conversion raises ``AttributeError`` instead of
+returning a quietly wrong value (the binding tests in ``tests/integration`` pin every field used here).
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Optional, Tuple
+
+_EPOCH = datetime(1970, 1, 1)
+
+_PROFIT_MODES = {0: "Forex", 1: "CFD", 2: "Futures"}
+
+
+def _time(value: Any) -> Optional[datetime]:
+    """A .NET ``DateTime`` (or ``datetime``) as a naive ``datetime``; the unset values (year 1, the Unix epoch) as ``None``."""
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        out = value.replace(tzinfo=None)
+    else:
+        year = int(value.Year)
+        if year <= 1:
+            return None
+        out = datetime(year, int(value.Month), int(value.Day), int(value.Hour), int(value.Minute),
+                       int(value.Second), int(value.Millisecond) * 1000)
+    return None if out <= _EPOCH else out
+
+
+def _name(value: Any) -> str:
+    """An enum value as its member name."""
+    return "" if value is None else str(value)
+
+
+def _opt_float(value: Any) -> Optional[float]:
+    """A double where NaN means "not known"."""
+    f = float(value)
+    return None if math.isnan(f) else f
+
+
+def _unset_if_zero(value: Any) -> Optional[float]:
+    f = float(value)
+    return None if f == 0.0 or math.isnan(f) else f
+
+
+# ---- market data ------------------------------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class Quote:
+    """A price. ``time`` is the server time of the tick (use it to judge how old the price is); ``high`` and ``low``
+    are the session's range once the server has sent it, and ``None`` before that."""
+    symbol: str
+    bid: float
+    ask: float
+    time: Optional[datetime] = None
+    high: Optional[float] = None
+    low: Optional[float] = None
+
+    @property
+    def spread(self) -> float:
+        return self.ask - self.bid
+
+    @classmethod
+    def _from_core(cls, q: Any) -> "Quote":
+        return cls(symbol=str(q.Symbol), bid=float(q.Bid), ask=float(q.Ask), time=_time(q.Time),
+                   high=_unset_if_zero(q.High), low=_unset_if_zero(q.Low))
+
+
+@dataclass(frozen=True)
+class SymbolInfo:
+    """A symbol's specification and trading rules, as the server publishes them.
+
+    ``contract_size`` and ``digits`` are reliable. ``currency`` is the currency the server lists for the symbol: the
+    profit currency of a CFD or futures symbol, the *base* currency of a Forex one; :attr:`profit_currency` gives the
+    currency profit is realised in for both. ``raw_tick_value`` and the two ``raw_*_tick_value`` fields are the
+    server's own and are often 0: never size a position from them (use :meth:`Client.tick_value` and
+    :meth:`Client.lots_for_risk`). ``min_lots`` / ``max_lots`` / ``lots_step`` are 0 when the account's group published
+    none.
+    """
+    name: str
+    digits: int
+    point: float
+    currency: str
+    profit_mode: str               # Forex, CFD or Futures
+    contract_size: float
+    margin_divider: float
+    tick_size: float
+    execution: str                 # Request, Instant, Market or Exchange
+    security_index: int            # the account group's security (symbol class) the volume rules are keyed on
+    min_lots: float
+    max_lots: float
+    lots_step: float
+    code: int                      # the feed code the server uses for this symbol
+    raw_tick_value: float = 0.0
+    raw_bid_tick_value: float = 0.0
+    raw_ask_tick_value: float = 0.0
+
+    @property
+    def profit_currency(self) -> str:
+        """The currency profit is realised in: the quote currency of a Forex symbol (the last three letters of its
+        six-letter name, the way the core prices it), the listed currency otherwise."""
+        if self.profit_mode == "Forex" and len(self.name) >= 6 and self.name[:6].isalpha():
+            return self.name[3:6].upper()
+        return self.currency
+
+    @classmethod
+    def _from_core(cls, s: Any) -> "SymbolInfo":
+        digits = int(s.Digits)
+        mode = int(s.ProfitMode)
+        return cls(name=str(s.Name), digits=digits, point=10.0 ** -digits, currency=str(s.Currency or ""),
+                   profit_mode=_PROFIT_MODES.get(mode, "Mode%d" % mode), contract_size=float(s.ContractSize),
+                   margin_divider=float(s.MarginDivider), tick_size=float(s.TickSize), execution=_name(s.ExecutionType),
+                   security_index=int(s.SecurityIndex), min_lots=float(s.MinLot), max_lots=float(s.MaxLot),
+                   lots_step=float(s.LotStep), code=int(s.Code), raw_tick_value=float(s.TickValue),
+                   raw_bid_tick_value=float(s.BidTickValue), raw_ask_tick_value=float(s.AskTickValue))
+
+
+@dataclass(frozen=True)
+class SymbolGroup:
+    """One of the broker's configured symbol groups (its name and description)."""
+    name: str
+    description: str
+
+    @classmethod
+    def _from_core(cls, g: Any) -> "SymbolGroup":
+        return cls(name=str(g.Name or ""), description=str(g.Description or ""))
+
+
+# ---- the account ------------------------------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class AccountInfo:
+    """The account at the moment it was read. ``equity``, ``profit``, ``margin``, ``free_margin`` and ``margin_level``
+    are derived on the client from the live quotes (the server does not push them), exactly as the terminal does.
+    ``priced_from`` is the server time of the oldest tick those figures were priced from (``None`` with no open
+    position): minutes old while the market is open means the feed is not delivering — do not trust the equity."""
+    login: int
+    name: str
+    company: str
+    group: str
+    currency: str
+    leverage: int
+    balance: float
+    credit: float
+    equity: float
+    profit: float
+    margin: float
+    free_margin: float
+    margin_level: float
+    account_type: str              # Real, Demo or Contest (a demo server can stamp Real: it is the server's class)
+    is_investor: bool = False
+    priced_from: Optional[datetime] = None
+
+
+@dataclass(frozen=True)
+class AccountSummary:
+    """Realized totals over a history range (from the closed-order ledger, not the floating P/L of open positions)."""
+    balance: float
+    credit: float
+    realized_profit: float         # closed trades: profit + commission + swap
+    deposit: float
+    withdrawal: float              # negative or zero
+
+    @classmethod
+    def _from_core(cls, s: Any) -> "AccountSummary":
+        return cls(balance=float(s.Balance), credit=float(s.Credit), realized_profit=float(s.RealizedProfit),
+                   deposit=float(s.Deposit), withdrawal=float(s.Withdrawal))
+
+
+@dataclass(frozen=True)
+class EquityPoint:
+    """One sample of the balance and equity curve. ``balance_change`` is the change of balance since the first point
+    (deposits and withdrawals included, so it is not a trading result: use :class:`AccountSummary`)."""
+    time: Optional[datetime]
+    balance: float
+    equity: float
+    balance_change: float
+    unrealized_pl: float
+    balance_drawdown_raw: float
+    balance_drawdown_relative: float
+    equity_drawdown_raw: float
+    equity_drawdown_relative: float
+
+    @classmethod
+    def _from_core(cls, p: Any) -> "EquityPoint":
+        return cls(time=_time(p.Time), balance=float(p.Balance), equity=float(p.Equity),
+                   balance_change=float(p.BalanceChange), unrealized_pl=float(p.UnrealizedPL),
+                   balance_drawdown_raw=float(p.BalanceDrawdownRaw),
+                   balance_drawdown_relative=float(p.BalanceDrawdownRelative),
+                   equity_drawdown_raw=float(p.EquityDrawdownRaw),
+                   equity_drawdown_relative=float(p.EquityDrawdownRelative))
+
+
+@dataclass(frozen=True)
+class LotSizing:
+    """The answer of :meth:`Client.lots_for_risk`. If ``ok`` is false, ``lots`` is 0 and ``reason`` says why: do not
+    trade it. ``warnings`` can accompany a true ``ok`` (most often that the broker's minimum volume risks more than
+    was asked)."""
+    ok: bool
+    lots: float
+    expected_loss_at_stop: float
+    risk_requested: float
+    minimum_trade_cost: float
+    ratio: float
+    reason: str
+    warnings: Tuple[str, ...]
+
+    @classmethod
+    def _from_core(cls, r: Any) -> "LotSizing":
+        return cls(ok=bool(r.Ok), lots=float(r.Lots), expected_loss_at_stop=float(r.ExpectedLossAtStop),
+                   risk_requested=float(r.RiskRequested), minimum_trade_cost=float(r.MinimumTradeCost),
+                   ratio=float(r.Ratio), reason=str(r.Reason or ""),
+                   warnings=tuple(str(w) for w in (r.Warnings or ())))
+
+
+# ---- orders ------------------------------------------------------------------------------------------------------
+
+_MARKET = ("Buy", "Sell")
+_PENDING = ("BuyLimit", "SellLimit", "BuyStop", "SellStop")
+
+
+@dataclass(frozen=True)
+class Order:
+    """One MT4 order: an open position, a pending order, a closed order of the history, or a balance / credit entry.
+
+    MT4 keeps one record for all of them. ``order_type`` is ``Buy`` or ``Sell`` for a market position (open, or closed
+    when ``close_time`` is set), ``BuyLimit`` / ``SellLimit`` / ``BuyStop`` / ``SellStop`` for a pending order, and
+    ``Balance`` / ``Credit`` for a ledger entry (the amount is in ``profit``, ``symbol`` is empty).
+    ``magic`` is read back from the server; the core cannot set it on an order (see :meth:`Client.buy`).
+    """
+    ticket: int
+    symbol: str
+    order_type: str
+    lots: float
+    open_time: Optional[datetime]
+    open_price: float
+    stop_loss: float
+    take_profit: float
+    close_time: Optional[datetime]
+    close_price: float
+    expiration: Optional[datetime]
+    magic: int
+    swap: float
+    commission: float
+    comment: str
+    profit: float
+    rate_open: float = 0.0
+    rate_close: float = 0.0
+    rate_margin: float = 0.0
+
+    @property
+    def is_market(self) -> bool:
+        """A market position (``Buy`` or ``Sell``)."""
+        return self.order_type in _MARKET
+
+    @property
+    def is_pending(self) -> bool:
+        """A pending order (a limit or a stop)."""
+        return self.order_type in _PENDING
+
+    @property
+    def is_capital_flow(self) -> bool:
+        """A balance or credit entry (deposit, withdrawal, bonus), not a trade."""
+        return self.order_type in ("Balance", "Credit")
+
+    @property
+    def is_buy(self) -> bool:
+        """The order is on the buy side (market or pending)."""
+        return self.order_type.startswith("Buy")
+
+    @classmethod
+    def _from_core(cls, o: Any) -> "Order":
+        return cls(ticket=int(o.Ticket), symbol=str(o.Symbol or ""), order_type=_name(o.Type), lots=float(o.Lots),
+                   open_time=_time(o.OpenTime), open_price=float(o.OpenPrice), stop_loss=float(o.StopLoss),
+                   take_profit=float(o.TakeProfit), close_time=_time(o.CloseTime), close_price=float(o.ClosePrice),
+                   expiration=_time(o.ExpirationTime), magic=int(o.ExpertId), swap=float(o.Swap),
+                   commission=float(o.Commission), comment=str(o.Comment or ""), profit=float(o.Profit),
+                   rate_open=float(o.RateOpen), rate_close=float(o.RateClose), rate_margin=float(o.RateMargin))
+
+
+@dataclass(frozen=True)
+class OrderUpdate:
+    """A change the server pushed: ``action`` is one of ``PositionOpen``, ``PositionClose``, ``PositionModify``,
+    ``PendingOpen``, ``PendingClose``, ``PendingModify``, ``PendingFill``, ``Balance``, ``Credit`` (a pending order that
+    fills arrives as ``PositionOpen``)."""
+    action: str
+    order: Order
+
+    @classmethod
+    def _from_core(cls, u: Any) -> "OrderUpdate":
+        return cls(action=_name(u.Action), order=Order._from_core(u.Order))
+
+
+@dataclass(frozen=True)
+class OrderProgress:
+    """Progress of a trade request, as the request id (the integer :meth:`Client.buy_async` and friends return)
+    advances through the server: ``stage`` is ``InProcess``, ``Accepted``, ``Opened``, ``Closed``, ``Modified``,
+    ``PendingDeleted``, ``ClosedBy``, ``MultipleClosedBy``, ``Price`` or ``Exception`` (``Rejected`` and ``Timeout`` are
+    defined by the core but never raised by it). ``order`` is set where the server returned one, ``error`` for an
+    ``Exception`` stage (a pmt4api error such as :class:`ServerError`)."""
+    request_id: int
+    stage: str
+    order: Optional[Order] = None
+    error: Optional[BaseException] = None
+
+
+@dataclass(frozen=True)
+class ConnectEvent:
+    """A session started (``connected`` true: the first connect and every reconnect) or ended (``connected`` false;
+    ``error`` is the reason for a drop and ``None`` when you closed the client yourself)."""
+    connected: bool
+    error: Optional[BaseException] = None
+
+
+# ---- offline files -----------------------------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class ServerRecord:
+    """A broker of a ``servers.ini`` file: its name, company, demo flag, main host and (host, port) access servers."""
+    name: str
+    company: str
+    is_demo: bool
+    main_host: str
+    access: Tuple[Tuple[str, int], ...]
+
+    @classmethod
+    def _from_core(cls, r: Any) -> "ServerRecord":
+        return cls(name=str(r.Name or ""), company=str(r.Company or ""), is_demo=bool(r.IsDemo),
+                   main_host=str(r.MainHost or ""),
+                   access=tuple((str(a.Item1), int(a.Item2)) for a in (r.Access or ())))

pmt4api/servers.py

@@ -0,0 +1,40 @@
+"""Offline helpers that do not need a connected client."""
+from __future__ import annotations
+
+import os
+from typing import Iterable, List, Union
+
+from . import _runtime
+from ._util import translated
+from .models import ServerRecord
+
+
+@translated
+def load_servers_ini(source: Union[str, "os.PathLike[str]", bytes]) -> List[ServerRecord]:
+    """The brokers in a terminal's ``servers.ini``: each with its name, company, demo flag, main host and
+    ``(host, port)`` access servers. Offline: reads only the file (a path, or the file's bytes)."""
+    core = _runtime.load()
+    if isinstance(source, (bytes, bytearray)):
+        import System  # noqa: PLC0415
+        records = core.MT4API.LoadServersIni(System.Array[System.Byte](bytes(source)))
+    else:
+        records = core.MT4API.LoadServersIni(os.fspath(source))
+    return [ServerRecord._from_core(r) for r in (records or ())]
+
+
+@translated
+def save_servers_ini(records: Iterable[ServerRecord]) -> bytes:
+    """The bytes of a ``servers.ini`` file holding ``records`` (the inverse of :func:`load_servers_ini`)."""
+    core = _runtime.load()
+    import System  # noqa: PLC0415
+    Access = System.ValueTuple[System.String, System.Int32]
+    built = []
+    for rec in records:
+        r = core.Mt4Server()
+        r.Name = rec.name
+        r.Company = rec.company
+        r.IsDemo = bool(rec.is_demo)
+        r.MainHost = rec.main_host
+        r.Access = System.Array[Access]([Access(host, int(port)) for host, port in rec.access])
+        built.append(r)
+    return bytes(core.MT4API.SaveServersIni(System.Array[core.Mt4Server](built)))