pmt5api 1.0.0__py3-none-any.whl

pmt5api/models.py

@@ -0,0 +1,522 @@
+"""Plain Python value types returned by :class:`pmt5api.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, field
+from datetime import datetime
+from typing import Any, Dict, Optional, Tuple
+
+_EPOCH = datetime(1970, 1, 1)
+
+
+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
+
+
+# ---- market data ------------------------------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class Quote:
+    symbol: str
+    bid: float
+    ask: float
+    time: Optional[datetime]
+    last: float
+    volume: int
+
+    @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),
+                   last=float(q.Last), volume=int(q.Volume))
+
+
+@dataclass(frozen=True)
+class SymbolInfo:
+    """A symbol's specification and trading rules.
+
+    ``raw_tick_value`` / ``raw_tick_size`` are the server's own fields and brokers often report them as 0: never size a
+    position from them (use :meth:`Client.tick_value` and :meth:`Client.lots_for_risk`).
+    """
+    name: str
+    description: str
+    digits: int
+    point: float
+    spread: int
+    contract_size: float
+    profit_currency: str
+    margin_currency: str
+    isin: str = ""
+    custom: bool = False
+    depth_of_market: int = 0
+    calc_mode: str = ""
+    gtc_mode: str = ""
+    settlement_price: float = 0.0
+    lower_limit: float = 0.0
+    upper_limit: float = 0.0
+    face_value: float = 0.0
+    accrued_interest: float = 0.0
+    raw_tick_value: float = 0.0
+    raw_tick_size: float = 0.0
+    # trading rules of the symbol's group
+    group: str = ""
+    trade_mode: str = ""
+    execution: str = ""
+    min_lots: float = 0.0
+    max_lots: float = 0.0
+    lots_step: float = 0.0
+    min_stop_distance: int = 0       # minimum stop-loss distance, points
+    min_take_distance: int = 0       # minimum take-profit distance, points
+    swap_type: str = ""
+    swap_long: float = 0.0
+    swap_short: float = 0.0
+    triple_swap_day: str = ""
+    initial_margin: float = 0.0
+    maintenance_margin: float = 0.0
+
+    @classmethod
+    def _from_core(cls, name: str, s: Any, group: Any = None) -> "SymbolInfo":
+        extra: Dict[str, Any] = {}
+        if group is not None:
+            extra = dict(group=str(group.GroupName or ""), trade_mode=_name(group.TradeMode),
+                         execution=_name(group.TradeType), min_lots=float(group.MinLots), max_lots=float(group.MaxLots),
+                         lots_step=float(group.LotsStep), min_stop_distance=int(group.SL),
+                         min_take_distance=int(group.TP), swap_type=_name(group.SwapType),
+                         swap_long=float(group.SwapLong), swap_short=float(group.SwapShort),
+                         triple_swap_day=_name(group.ThreeDaysSwap), initial_margin=float(group.InitialMargin),
+                         maintenance_margin=float(group.MaintenanceMargin))
+        return cls(name=name or str(s.Currency), description=str(s.Description or ""), digits=int(s.Digits),
+                   point=float(s.Points), spread=int(s.Spread), contract_size=float(s.ContractSize),
+                   profit_currency=str(s.ProfitCurrency or ""), margin_currency=str(s.MarginCurrency or ""),
+                   isin=str(s.ISIN or ""), custom=bool(int(s.Custom)), depth_of_market=int(s.DepthOfMarket),
+                   calc_mode=_name(s.CalcMode), gtc_mode=_name(s.GTCMode), settlement_price=float(s.SettlementPrice),
+                   lower_limit=float(s.LowerLimit), upper_limit=float(s.UpperLimit), face_value=float(s.FaceValue),
+                   accrued_interest=float(s.AccruedInterest), raw_tick_value=float(s.TickValue),
+                   raw_tick_size=float(s.TickSize), **extra)
+
+
+@dataclass(frozen=True)
+class TradingSession:
+    """One trading or quoting window of a weekday, in minutes from 00:00 server time (``end`` may be 1440)."""
+    start: int
+    end: int
+
+
+@dataclass(frozen=True)
+class SymbolSessions:
+    """Per weekday (index 0 = Sunday … 6 = Saturday), the windows in which a symbol is quoted and traded."""
+    symbol: str
+    quotes: Tuple[Tuple[TradingSession, ...], ...]
+    trades: Tuple[Tuple[TradingSession, ...], ...]
+
+    @classmethod
+    def _from_core(cls, symbol: str, s: Any) -> "SymbolSessions":
+        def week(days: Any) -> Tuple[Tuple[TradingSession, ...], ...]:
+            return tuple(tuple(TradingSession(int(x.StartTime), int(x.EndTime)) for x in (day or ())) for day in days)
+        return cls(symbol=symbol, quotes=week(s.Quotes), trades=week(s.Trades))
+
+
+@dataclass(frozen=True)
+class CommissionTier:
+    unit_type: str
+    unit_mode: str
+    unit_value: float
+    min_value: float
+    max_value: float
+    min_unit: float
+    max_unit: float
+    currency_unit: str
+
+
+@dataclass(frozen=True)
+class CommissionInfo:
+    group_name: str
+    type: str
+    period: str
+    money_currency: str
+    instant_type: str
+    tiers: Tuple[CommissionTier, ...]
+
+    @classmethod
+    def _from_core(cls, c: Any) -> "CommissionInfo":
+        tiers = tuple(CommissionTier(unit_type=_name(t.UnitType), unit_mode=_name(t.UnitMode),
+                                     unit_value=float(t.UnitValue), min_value=float(t.MinValue),
+                                     max_value=float(t.MaxValue), min_unit=float(t.MinUnit),
+                                     max_unit=float(t.MaxUnit), currency_unit=str(t.CurrencyUnit or ""))
+                      for t in (c.Comissions or ()))
+        return cls(group_name=str(c.GroupName or ""), type=_name(c.Type), period=_name(c.Period),
+                   money_currency=str(c.MoneyCurrency or ""), instant_type=_name(c.InstantType), tiers=tiers)
+
+
+# ---- account ----------------------------------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class AccountInfo:
+    login: int
+    name: str
+    currency: str
+    leverage: int
+    balance: float
+    credit: float
+    equity: float
+    profit: float             # floating P/L of open positions including swap, commission and fee (the core's AccountProfit)
+    margin: float
+    free_margin: float
+    margin_level: float
+    floating_pl: float = 0.0  # the price-driven part of ``profit`` alone
+    swap: float = 0.0
+    commission: float = 0.0
+    fee: float = 0.0
+    blocked: float = 0.0
+    company: str = ""
+    method: str = ""          # "Netting" or "Hedging"
+    account_type: str = ""
+    trade_flags: int = 0
+    country: str = ""
+    city: str = ""
+    state: str = ""
+    zip_code: str = ""
+    address: str = ""
+    phone: str = ""
+    email: str = ""
+
+
+@dataclass(frozen=True)
+class BaseInfo:
+    """What the server says about itself: the broker, the account currency and its digits, the account mode."""
+    company: str
+    currency: str
+    digits: int
+    account_method: str     # "Netting" or "Hedging"
+    margin_mode: str
+
+    @classmethod
+    def _from_core(cls, b: Any) -> "BaseInfo":
+        return cls(company=str(b.CompanyName or ""), currency=str(b.Currency or ""), digits=int(b.Digits),
+                   account_method=_name(b.AccMethod), margin_mode=_name(b.MarginMode))
+
+
+@dataclass(frozen=True)
+class AccountSummary:
+    """Realized figures from the deal ledger: trading result apart from deposits and withdrawals."""
+    balance: float
+    credit: float
+    realized_profit: float
+    deposit: float
+    withdrawal: float
+
+    @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 point of the balance/equity curve. ``balance`` and ``balance_change`` are exact (the deal ledger); the
+    historical ``equity`` and ``unrealized_pl`` are a bar-priced reconstruction. ``incomplete`` is set when a symbol's
+    bars did not arrive in time, so the floating part of that point is understated."""
+    time: Optional[datetime]
+    balance: float
+    equity: float
+    balance_drawdown_raw: float
+    balance_drawdown_relative: float
+    equity_drawdown_raw: float
+    equity_drawdown_relative: float
+    realized_pl: float
+    unrealized_pl: float
+    incomplete: bool
+    balance_change: float
+
+    @classmethod
+    def _from_core(cls, p: Any) -> "EquityPoint":
+        return cls(time=_time(p.Time), balance=float(p.Balance), equity=float(p.Equity),
+                   balance_drawdown_raw=float(p.BalanceDrawdownRaw),
+                   balance_drawdown_relative=float(p.BalanceDrawdownRelative),
+                   equity_drawdown_raw=float(p.EquityDrawdownRaw),
+                   equity_drawdown_relative=float(p.EquityDrawdownRelative), realized_pl=float(p.RealizedPL),
+                   unrealized_pl=float(p.UnrealizedPL), incomplete=bool(p.Incomplete),
+                   balance_change=float(p.BalanceChange))
+
+
+@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`` (for example, nothing corroborated the scale)."""
+    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, deals, history --------------------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class Order:
+    """An open position, a pending order, or a historical order."""
+    ticket: int
+    symbol: str
+    order_type: str
+    deal_type: str
+    state: str
+    lots: float
+    digits: int
+    open_price: float
+    open_time: Optional[datetime]
+    close_price: float
+    close_time: Optional[datetime]
+    stop_loss: float
+    take_profit: float
+    profit: float
+    swap: float
+    commission: float
+    fee: float
+    comment: str
+    magic: int          # the expert / magic number the order was sent with (0 if none)
+    close_lots: float = 0.0
+    close_comment: str = ""
+    contract_size: float = 0.0
+    placed_type: str = ""
+    request_id: int = 0
+    stop_limit_price: float = 0.0
+    profit_rate: float = 0.0
+    expiration_type: str = ""
+    expiration_time: Optional[datetime] = None
+    fill_policy: str = ""
+
+    @classmethod
+    def _from_core(cls, o: Any) -> "Order":
+        return cls(ticket=int(o.Ticket), symbol=str(o.Symbol or ""), order_type=_name(o.OrderType),
+                   deal_type=_name(o.DealType), state=_name(o.State), lots=float(o.Lots), digits=int(o.Digits),
+                   open_price=float(o.OpenPrice), open_time=_time(o.OpenTime), close_price=float(o.ClosePrice),
+                   close_time=_time(o.CloseTime), stop_loss=float(o.StopLoss), take_profit=float(o.TakeProfit),
+                   profit=float(o.Profit), swap=float(o.Swap), commission=float(o.Commission), fee=float(o.Fee),
+                   comment=str(o.Comment or ""), magic=int(o.ExpertId), close_lots=float(o.CloseLots),
+                   close_comment=str(o.CloseComment or ""), contract_size=float(o.ContractSize),
+                   placed_type=_name(o.PlacedType), request_id=int(o.RequestId),
+                   stop_limit_price=float(o.StopLimitPrice), profit_rate=float(o.ProfitRate),
+                   expiration_type=_name(o.ExpirationType), expiration_time=_time(o.ExpirationTime),
+                   fill_policy=_name(o.FillPolicy))
+
+
+@dataclass(frozen=True)
+class Deal:
+    """One executed deal from the account's ledger (a trade fill, or a balance operation such as a deposit)."""
+    ticket: int
+    order_ticket: int
+    position_ticket: int
+    symbol: str
+    type: str
+    direction: str
+    time: Optional[datetime]
+    price: float
+    open_price: float
+    stop_loss: float
+    take_profit: float
+    lots: float
+    profit: float
+    commission: float
+    swap: float
+    contract_size: float
+    digits: int
+    comment: str
+    magic: int          # the expert / magic number of the order that produced the deal
+
+    @classmethod
+    def _from_core(cls, d: Any) -> "Deal":
+        return cls(ticket=int(d.Ticket), order_ticket=int(d.OrderTicket), position_ticket=int(d.PositionTicket),
+                   symbol=str(d.Symbol or ""), type=_name(d.Type), direction=_name(d.Direction), time=_time(d.Time),
+                   price=float(d.Price), open_price=float(d.OpenPrice), stop_loss=float(d.StopLoss),
+                   take_profit=float(d.TakeProfit), lots=float(d.Lots), profit=float(d.Profit),
+                   commission=float(d.Commission), swap=float(d.Swap), contract_size=float(d.ContractSize),
+                   digits=int(d.Digits), comment=str(d.Comment or ""), magic=int(d.ExpertId))
+
+
+@dataclass(frozen=True)
+class History:
+    """Result of a history download: the orders and the deals in the requested window."""
+    orders: Tuple[Order, ...] = field(default_factory=tuple)
+    deals: Tuple[Deal, ...] = field(default_factory=tuple)
+    action: int = 0                 # the server's action code; 14 means more pages follow
+
+    @property
+    def more(self) -> bool:
+        """Another page of this history follows (only seen on the event-driven path)."""
+        return self.action == 14
+
+    @classmethod
+    def _from_core(cls, h: Any) -> "History":
+        return cls(orders=tuple(Order._from_core(o) for o in (h.Orders or ())),
+                   deals=tuple(Deal._from_core(d) for d in (h.Deals or ())), action=int(h.Action))
+
+
+# ---- events -----------------------------------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class OrderUpdate:
+    """A change the server pushed about an order or a position. ``type`` is one of Started, Filled, PendingOpen,
+    PendingModify, PendingClose, MarketOpen, MarketModify, MarketClose, PartialClose, MarketCloseBy, OnStopLoss,
+    OnTakeProfit, OnStopOut, Balance, Expired, Rejected, Cancelling, Unknown.
+
+    ``ticket`` is the ticket of ``order`` (0 when the update carries no order, such as a balance operation);
+    ``transaction_id`` is the server's identifier of the transaction itself.
+    """
+    type: str
+    order: Optional[Order]
+    ticket: int
+    transaction_id: int
+    close_by_ticket: int
+
+    @classmethod
+    def _from_core(cls, u: Any) -> "OrderUpdate":
+        order = Order._from_core(u.Order) if u.Order is not None else None
+        return cls(type=_name(u.Type), order=order, ticket=order.ticket if order is not None else 0,
+                   transaction_id=int(u.Trans.TicketNumber) if u.Trans is not None else 0,
+                   close_by_ticket=int(u.CloseByTicket))
+
+
+@dataclass(frozen=True)
+class OrderProgress:
+    """Progress of an asynchronous trade request (the request id you got back from ``*_async``)."""
+    request_id: int
+    status: str            # the server's answer, e.g. Done, Requote, Invalid ...
+    ticket: int
+    position_id: int
+    volume: float          # lots
+    price: float
+    bid: float
+    ask: float
+    comment: str
+    order_type: str
+    symbol: str
+    fill_policy: str       # the fill policy the request carried
+
+    @classmethod
+    def _from_core(cls, p: Any) -> "OrderProgress":
+        req, res = p.TradeRequest, p.TradeResult
+        symbol = ""
+        if p.OrderUpdate is not None:
+            symbol = str(getattr(p.OrderUpdate, "Currency", "") or "")
+        elif req is not None:
+            symbol = str(req.Currency or "")
+        return cls(request_id=int(req.RequestId) if req is not None else 0,
+                   status=_name(res.Status) if res is not None else "",
+                   ticket=int(res.TicketNumber) if res is not None else 0,
+                   position_id=int(res.PositionId) if res is not None else 0,
+                   volume=float(res.Volume) / 100000000.0 if res is not None else 0.0,
+                   price=float(res.OpenPrice) if res is not None else 0.0,
+                   bid=float(res.Bid) if res is not None else 0.0, ask=float(res.Ask) if res is not None else 0.0,
+                   comment=str(res.Comment or "") if res is not None else "",
+                   order_type=_name(req.OrderType) if req is not None else "", symbol=symbol,
+                   fill_policy=_name(req.FillPolicy) if req is not None else "")
+
+
+@dataclass(frozen=True)
+class ConnectEvent:
+    """A step of the connect sequence: SendLogin, SendAccountPassword, AcceptAuthorized, RequestTradeInfo, Connected,
+    Exception, Disconnect. ``error`` is the translated exception for ``Exception`` steps."""
+    stage: str
+    error: Optional[BaseException] = None
+
+
+# ---- offline files and account admin ------------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class ServerRecord:
+    """A trade server of a ``servers.dat`` file: its name, company and (host, port) access points."""
+    name: str
+    company: 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 ""),
+                   access=tuple((str(a.Item1), int(a.Item2)) for a in (r.Access or ())))
+
+
+@dataclass(frozen=True)
+class DemoAccountRequest:
+    """What :func:`pmt5api.request_demo_account` asks a broker's server for."""
+    user_name: str
+    email: str
+    deposit: float = 10000.0
+    leverage: int = 100
+    account_type: str = ""
+    country: str = ""
+    city: str = ""
+    state: str = ""
+    zip_code: str = ""
+    address: str = ""
+    phone: str = ""
+    company_name: str = ""
+    language_id: int = 0
+
+
+@dataclass(frozen=True)
+class DemoAccount:
+    login: int
+    password: str
+    investor_password: str
+
+
+def _symbols_from_core(infos: Any, groups: Any = None) -> Dict[str, SymbolInfo]:
+    """``infos`` is the core's name -> SymbolInfo dictionary; ``groups`` is the core's ``Symbols`` object, used to
+    attach each symbol's group rules."""
+    out: Dict[str, SymbolInfo] = {}
+    for kv in infos or ():
+        if kv.Value is None:
+            continue
+        name = str(kv.Key) if kv.Key is not None else ""
+        group = None
+        if groups is not None:
+            try:
+                group = groups.GetGroup(name)
+            except Exception:  # noqa: BLE001 — a symbol without a group still has its own record
+                group = None
+        info = SymbolInfo._from_core(name, kv.Value, group)
+        out[info.name] = info
+    return out

pmt5api/servers.py

@@ -0,0 +1,73 @@
+"""Offline helpers and account administration 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 DemoAccount, DemoAccountRequest, ServerRecord
+
+
+@translated
+def load_servers_dat(source: Union[str, "os.PathLike[str]", bytes]) -> List[ServerRecord]:
+    """The trade servers in a terminal's ``servers.dat``: each with its name, company and (host, port) access points.
+    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.MT5API.LoadServersDat(System.Array[System.Byte](bytes(source)))
+    else:
+        records = core.MT5API.LoadServersDat(os.fspath(source))
+    return [ServerRecord._from_core(r) for r in (records or ())]
+
+
+@translated
+def save_servers_dat(records: Iterable[ServerRecord]) -> bytes:
+    """The bytes of a ``servers.dat`` file holding ``records`` (the inverse of :func:`load_servers_dat`)."""
+    core = _runtime.load()
+    import System  # noqa: PLC0415
+    Access = System.ValueTuple[System.String, System.Int32]
+    built = []
+    for rec in records:
+        r = core.ServerRecord()
+        r.Name = rec.name
+        r.Company = rec.company
+        r.Access = System.Array[Access]([Access(host, int(port)) for host, port in rec.access])
+        built.append(r)
+    return bytes(core.MT5API.SaveServersDat(System.Array[core.ServerRecord](built)))
+
+
+@translated
+def request_demo_account(request: DemoAccountRequest, host: str, port: int = 443) -> DemoAccount:
+    """Ask a broker's access server for a new demo account and return its login and passwords.
+
+    This creates a real account at the broker: use it deliberately.
+    """
+    core = _runtime.load()
+    req = core.AccountRequest()
+    req.UserName = request.user_name
+    req.Email = request.email
+    req.Deposit = float(request.deposit)
+    req.Leverage = int(request.leverage)
+    req.AccType = request.account_type
+    req.Country = request.country
+    req.City = request.city
+    req.State = request.state
+    req.ZipCode = request.zip_code
+    req.Address = request.address
+    req.Phone = request.phone
+    req.CompanyName = request.company_name
+    req.LanguageId = int(request.language_id)
+    answer = core.MT5API.RequestDemoAccount(req, host, int(port))
+    return DemoAccount(login=int(answer.Login), password=str(answer.Password or ""),
+                       investor_password=str(answer.Investor or ""))
+
+
+@translated
+def tick_value_from_deal(closed_profit: float, open_price: float, close_price: float, lots: float) -> float:
+    """The value of one price unit per lot implied by a closed deal's realized P/L — the empirical check of a
+    tick value."""
+    core = _runtime.load()
+    return float(core.MT5API.ComputeTickValueFromDeal(float(closed_profit), float(open_price), float(close_price),
+                                                      float(lots)))