pmt4api 1.0.0__tar.gz → 1.1.2__tar.gz

pmt4api-1.1.2/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog — pmt4api
+
+## [1.1.2] — 2026-10-15
+
+From the delta re-test of 1.1.1 (no S1 or S2). Python layer only: the cores are unchanged.
+
+### Fixed
+- `Order` money fields (profit, swap, commission) carry no binary noise.
+- README: a connect to an unreachable licence service waits several times `token_timeout` (about 44 s at the default 10: the retry, and each server of the list).
+
+## [1.1.1] — 2026-10-14
+
+From the Windows re-test of 1.1.0 (13 notes, one S2). Bundles wmt4api 3.3.1.
+
+### Fixed
+- A licence request no longer parks its connection (core `wmt4api 3.3.1`): repeated `history()` calls held about four
+  handles each until the next garbage collection.
+- A missing .NET runtime on a **32-bit** Python says that 32-bit Python needs the 32-bit runtime.
+- A quote-history timeout says how long it waited.
+- README: how to read why a position closed (`[sl]` / `[tp]` in the comment), Ctrl+C during `connect()`, the licence
+  request retry.
+
+## [1.1.0] — 2026-10-13
+
+Found by a customer-style test on Windows Server 2022 / Python 3.10 (28 findings); every one is addressed. Bundles
+wmt4api 3.3.0. Additive: nothing that worked in 1.0.0 is removed.
+
+### Fixed
+- **Two packages could not start the .NET runtime from two threads at once** (`RuntimeNotFoundError` in one of them,
+  every time, on Linux as well). One lock now covers every `pmt*api` package in the process.
+- **`bars()` re-aggregated the whole series after every block** (MT5): a deep request was quadratic and timed out
+  (`D1` × 1000 took over two minutes of CPU). It counts as the blocks arrive and aggregates once; the default budget
+  is `bars_timeout` plus a second per two weeks of one-minute bars the request needs.
+- **A closed client left a thread behind** for every client that had used callbacks or `quotes()`: the callback
+  thread now ends at `disconnect()` (and when the client is dropped) and returns with the next event.
+- **Type checkers saw every method as `(*Any, **Any) -> Any`**: the decorator that translates errors now keeps the
+  signature.
+- Messages: a missing .NET runtime names the runtime and where to get it; the no-key text speaks `api_key=`; a bars
+  timeout states its real wait; a trade refusal names its code.
+- `python -m pmt4api --connect` / `pmt5api --connect` accept `host:port` in `PMT*_HOST`.
+- The reference gains a meaning for every field of the main data types.
+- `close()`, `modify()` and `cancel()` return the order they acted on, the same on both packages (`pmt5api`: `close()` returned an empty record and `modify()` `None`; `pmt4api`: `cancel()` returned `None`).
+- The core fixes: see wmt4api 3.3.0 — **the account balance and credit now follow closes, deposits and withdrawals in the session** (they stayed at their value from connect).
+
+### Added
+- `lots_for_risk(..., side="buy" | "sell")`: a stop on the wrong side of the entry is refused instead of being sized by its distance.
+- `reconnect_max_backoff` (seconds, default 30): the longest delay between reconnect attempts.
+
+## [1.0.0] — 2026-10-12
+First release: the complete Python interface to wmt4api 3.2.0 (the MetaTrader 4 client library).
+
+- Every public member and type of the C# `MT4API` / `OrderClient` classes is mapped to a Python counterpart, or has a
+  stated reason for not having one (`pmt4api.COVERAGE`, `pmt4api.TYPES`; a test fails when the core gains an
+  unaccounted member).
+- Market data (symbols, quotes, bars on the nine MT4 timeframes with paging), account, sizing and risk, order entry
+  (market, pending, modify, partial close, close-by, close-all-by, cancel; synchronous, with request ids and progress
+  events, and awaitable), history, summary and equity curve.
+- Callbacks, sync and async iterators, one ordered dispatcher thread per client, with back-pressure accounting.
+- A small error hierarchy; the MT4 trade-return codes by name; requotes carry the new prices.
+- `auto_reconnect`, `servers=` failover, a silence watchdog, `reconnect()`; `disconnect()` is final.
+- Refusals before anything is sent: a magic number the core cannot transmit, a volume the wire cannot carry, a
+  comment that would not read back.
+- Wheels: Linux x86-64 with the core and a .NET runtime bundled, and a pure wheel that carries the core.

{pmt4api-1.0.0 → pmt4api-1.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pmt4api
-Version: 1.0.0
+Version: 1.1.2
 Summary: Complete Python interface to the wmt4api MetaTrader 4 client library (market data, account, sizing, order entry, events).
 Project-URL: Homepage, https://mtapi.one
 Author: Sen Trading
@@ -39,19 +39,33 @@ both reads alike.
 
 **Parity with the C# library is measured, not claimed:** `pmt4api.COVERAGE` maps every public member of the C#
 `MT4API` and `OrderClient` classes to its Python counterpart (or states why it has none), and the test suite fails
-if the core gains a member that is not accounted for. [`docs/FROM-CSHARP.md`](src/pmt4api/docs/FROM-CSHARP.md) is
-that table; [`docs/API.md`](src/pmt4api/docs/API.md) is the reference.
+if the core gains a member that is not accounted for. `pmt4api/docs/FROM-CSHARP.md` (inside the installed package) is
+that table; `pmt4api/docs/API.md` (inside the installed package; `python -m pmt4api` prints its folder) is the reference.
 
 ## Install
 
-The **Linux x86-64 wheel** carries everything — the core and a .NET runtime — so there is nothing else to install:
-
 ```
-pip install pmt4api-<version>-py3-none-manylinux_2_28_x86_64.whl
+pip install pmt4api
 ```
 
-On any other platform use the `py3-none-any` wheel, which carries the core and needs a .NET 8 (or later) runtime on
-the machine (`dotnet --list-runtimes` should list `Microsoft.NETCore.App`).
+pip chooses the wheel for your platform. The **Linux x86-64 wheel** carries everything — the core and a .NET runtime —
+so there is nothing else to install. On any other platform the `py3-none-any` wheel carries the core and needs a .NET 8
+(or later) runtime on the machine (`dotnet --list-runtimes` should list `Microsoft.NETCore.App`). From a downloaded
+file: `pip install pmt4api-<version>-py3-none-<platform>.whl`.
+
+**Windows (x64).** Install the .NET 8 runtime once (`winget install Microsoft.DotNet.Runtime.8`, or the installer from
+https://dotnet.microsoft.com/download/dotnet/8.0), then `pip install pmt4api`. Check it with `python -m pmt4api`: it prints
+the versions, finds the runtime and constructs a client offline. Set the key in the shell that runs your program —
+PowerShell: `$env:WMT4API_KEY = "wk_..."`, cmd: `set WMT4API_KEY=wk_...`. A string the broker sent can hold characters your
+console's code page cannot print: set `PYTHONUTF8=1` (or run `chcp 65001`) to avoid a `UnicodeEncodeError`.
+
+**Windows (x64).** Use the `py3-none-any` wheel from PyPI — `pip install pmt4api` picks it — and install the .NET 8
+runtime once (`winget install Microsoft.DotNet.Runtime.8`, or the installer from
+https://dotnet.microsoft.com/download/dotnet/8.0); `dotnet --list-runtimes` must list `Microsoft.NETCore.App 8.x` or
+later. Check the install with `python -m pmt4api`: it prints the versions, finds the runtime and constructs a client
+offline. Set the key in the shell that runs your program — PowerShell: `$env:WMT4API_KEY = "wk_..."`, cmd:
+`set WMT4API_KEY=wk_...`. A library string can hold characters your console code page cannot print: set
+`PYTHONUTF8=1` (or run `chcp 65001`) to avoid a `UnicodeEncodeError` when you print what the broker sent.
 
 You also need your **API key** (`wk_…`, the same key you use with wmt4api):
 
@@ -104,6 +118,10 @@ Timeframes: `M1 M5 M15 M30 H1 H4 D1 W1 MN1` — the nine the MT4 server serves;
 (M1 is typically a few days), so a long request returns what exists; one request carries at most 32 767 bars and
 longer requests page backwards for you. `volume` is the tick volume.
 
+**MT4 and MT5 differ here.** The MT4 package returns completed bars only and excludes a bar that opens at `end=`; on
+MT5 `end=` includes the bar stamped exactly `end` and the bar still forming. Code that runs on both has to drop the
+forming MT5 bar itself.
+
 ### Live quotes
 
 ```python
@@ -146,14 +164,16 @@ drop the oldest item when the consumer falls behind, and detach on `close()` / `
 ## Trading
 
 ```python
+from datetime import timedelta
+
 o = c.buy("EURUSDm", 0.10, sl=1.0950, tp=1.1100, comment="bot-1")   # market order at the ask; sell() at the bid
-c.modify(o.ticket, sl=1.0970)                     # change stops; what you leave out keeps its value
-c.close(o.ticket, 0.05)                           # close half; close(ticket) closes it all
+c.modify(o.ticket, sl=1.0970)                     # change stops (returns the order as the server holds it)
+c.close(o.ticket, 0.05)                           # close half (returns the closing record); close(ticket) closes it all
 
 p = c.place_order("EURUSDm", "buy_stop", 0.10, 1.1200, sl=1.1150,
                   expiration=timedelta(days=2))   # also buy_limit sell_limit sell_stop; a datetime works too
 c.modify(p.ticket, price=1.1210)                  # a pending order's price; its expiration is kept
-c.cancel(p.ticket)
+c.cancel(p.ticket)                                # returns the order that was deleted
 
 c.close_by(a.ticket, b.ticket)                    # close one position against an opposite one (hedged accounts)
 c.close_all_by("EURUSDm")                         # ... every opposite pair of the symbol
@@ -192,7 +212,7 @@ remainder of the position may carry a new ticket: read `positions()`.
 ## Sizing and risk
 
 ```python
-r = c.lots_for_risk("EURUSDm", entry_price=1.1000, stop_price=1.0950, risk_amount=50.0)
+r = c.lots_for_risk("EURUSDm", entry_price=1.1000, stop_price=1.0950, risk_amount=50.0, side="buy")
 for w in r.warnings:
     print("warning:", w)                  # ok can still be True with a caveat (the broker's minimum volume risks more)
 if r.ok:
@@ -251,8 +271,8 @@ restored, cached snapshots are not. `disconnect()` is final: it also stops a rec
 | API key | `api_key=` | `WMT4API_KEY` (then `WMTAPI_KEY`) |
 | Licence service URL (leave at its default) | `token_url=` | `WMT4API_TOKEN_URL` |
 | Core library (only if you do not use a wheel that carries it) | `dll_path=` | `WMT4API_DLL` |
-| Timeouts (seconds, each > 0) | `connect_timeout` (one attempt on one server), `token_timeout`, `trade_timeout` (≥ 1), `quote_timeout` / `history_timeout` / `bars_timeout` (the defaults of `quote`, `history`, `bars`), `no_message_timeout` | — |
-| Reconnect | `auto_reconnect`, `reconnect_backoff`, `reconnect_max_attempts`, `servers=` | — |
+| Timeouts (seconds, each > 0) | `connect_timeout` (one attempt on one server; default 6), `token_timeout` (10), `trade_timeout` (30; ≥ 1), `quote_timeout` (5) / `history_timeout` (30) / `bars_timeout` (30) — the defaults of `quote`, `history`, `bars`, `no_message_timeout` (30; ≥ 10, or 0 for off) | — |
+| Reconnect | `auto_reconnect`, `reconnect_backoff` (3, doubling up to `reconnect_max_backoff`, 30), `reconnect_max_attempts` (0 = no limit), `servers=` | — |
 | Orders | `placed_type=` (`manual`, `expert`, `dealer` …), `comment_encoding=` (default `latin-1`) | — |
 | .NET runtime location | — | `DOTNET_ROOT` |
 
@@ -272,7 +292,15 @@ pmt4api.enable_core_logging()          # the core's own messages -> logging.getL
 
 `load_servers_ini(path_or_bytes)` / `save_servers_ini(records)` read and write a terminal's `servers.ini`.
 `python -m pmt4api` prints what is installed and whether it works here (`--connect` also reads an account, using
-`PMT4_LOGIN`, `PMT4_PASSWORD`, `PMT4_HOST`); the output holds no secrets.
+`PMT4_LOGIN`, `PMT4_PASSWORD`, `PMT4_HOST` — a bare host, or `host:port`, or the port in `PMT4_PORT`); the output holds
+no secrets.
+
+## What a closed order says about why
+
+An MT4 server pushes the same `PositionClose` update for a stop-loss, a take-profit and a close you asked for; the
+reason is in the order's `comment`, which the server suffixes with `[sl]` or `[tp]` for a stop or a take-profit hit.
+Pressing Ctrl+C while `connect()` is dialling is honoured when the dial ends (up to `connect_timeout`), not at once.
+`token_timeout` bounds one licence request; a failed request is tried again and a connect tries each server of the list, so a connect to an unreachable licence service can wait several times that (about 44 s at the default 10).
 
 ## Errors
 

{pmt4api-1.0.0 → pmt4api-1.1.2}/README.md

@@ -12,19 +12,33 @@ both reads alike.
 
 **Parity with the C# library is measured, not claimed:** `pmt4api.COVERAGE` maps every public member of the C#
 `MT4API` and `OrderClient` classes to its Python counterpart (or states why it has none), and the test suite fails
-if the core gains a member that is not accounted for. [`docs/FROM-CSHARP.md`](src/pmt4api/docs/FROM-CSHARP.md) is
-that table; [`docs/API.md`](src/pmt4api/docs/API.md) is the reference.
+if the core gains a member that is not accounted for. `pmt4api/docs/FROM-CSHARP.md` (inside the installed package) is
+that table; `pmt4api/docs/API.md` (inside the installed package; `python -m pmt4api` prints its folder) is the reference.
 
 ## Install
 
-The **Linux x86-64 wheel** carries everything — the core and a .NET runtime — so there is nothing else to install:
-
 ```
-pip install pmt4api-<version>-py3-none-manylinux_2_28_x86_64.whl
+pip install pmt4api
 ```
 
-On any other platform use the `py3-none-any` wheel, which carries the core and needs a .NET 8 (or later) runtime on
-the machine (`dotnet --list-runtimes` should list `Microsoft.NETCore.App`).
+pip chooses the wheel for your platform. The **Linux x86-64 wheel** carries everything — the core and a .NET runtime —
+so there is nothing else to install. On any other platform the `py3-none-any` wheel carries the core and needs a .NET 8
+(or later) runtime on the machine (`dotnet --list-runtimes` should list `Microsoft.NETCore.App`). From a downloaded
+file: `pip install pmt4api-<version>-py3-none-<platform>.whl`.
+
+**Windows (x64).** Install the .NET 8 runtime once (`winget install Microsoft.DotNet.Runtime.8`, or the installer from
+https://dotnet.microsoft.com/download/dotnet/8.0), then `pip install pmt4api`. Check it with `python -m pmt4api`: it prints
+the versions, finds the runtime and constructs a client offline. Set the key in the shell that runs your program —
+PowerShell: `$env:WMT4API_KEY = "wk_..."`, cmd: `set WMT4API_KEY=wk_...`. A string the broker sent can hold characters your
+console's code page cannot print: set `PYTHONUTF8=1` (or run `chcp 65001`) to avoid a `UnicodeEncodeError`.
+
+**Windows (x64).** Use the `py3-none-any` wheel from PyPI — `pip install pmt4api` picks it — and install the .NET 8
+runtime once (`winget install Microsoft.DotNet.Runtime.8`, or the installer from
+https://dotnet.microsoft.com/download/dotnet/8.0); `dotnet --list-runtimes` must list `Microsoft.NETCore.App 8.x` or
+later. Check the install with `python -m pmt4api`: it prints the versions, finds the runtime and constructs a client
+offline. Set the key in the shell that runs your program — PowerShell: `$env:WMT4API_KEY = "wk_..."`, cmd:
+`set WMT4API_KEY=wk_...`. A library string can hold characters your console code page cannot print: set
+`PYTHONUTF8=1` (or run `chcp 65001`) to avoid a `UnicodeEncodeError` when you print what the broker sent.
 
 You also need your **API key** (`wk_…`, the same key you use with wmt4api):
 
@@ -77,6 +91,10 @@ Timeframes: `M1 M5 M15 M30 H1 H4 D1 W1 MN1` — the nine the MT4 server serves;
 (M1 is typically a few days), so a long request returns what exists; one request carries at most 32 767 bars and
 longer requests page backwards for you. `volume` is the tick volume.
 
+**MT4 and MT5 differ here.** The MT4 package returns completed bars only and excludes a bar that opens at `end=`; on
+MT5 `end=` includes the bar stamped exactly `end` and the bar still forming. Code that runs on both has to drop the
+forming MT5 bar itself.
+
 ### Live quotes
 
 ```python
@@ -119,14 +137,16 @@ drop the oldest item when the consumer falls behind, and detach on `close()` / `
 ## Trading
 
 ```python
+from datetime import timedelta
+
 o = c.buy("EURUSDm", 0.10, sl=1.0950, tp=1.1100, comment="bot-1")   # market order at the ask; sell() at the bid
-c.modify(o.ticket, sl=1.0970)                     # change stops; what you leave out keeps its value
-c.close(o.ticket, 0.05)                           # close half; close(ticket) closes it all
+c.modify(o.ticket, sl=1.0970)                     # change stops (returns the order as the server holds it)
+c.close(o.ticket, 0.05)                           # close half (returns the closing record); close(ticket) closes it all
 
 p = c.place_order("EURUSDm", "buy_stop", 0.10, 1.1200, sl=1.1150,
                   expiration=timedelta(days=2))   # also buy_limit sell_limit sell_stop; a datetime works too
 c.modify(p.ticket, price=1.1210)                  # a pending order's price; its expiration is kept
-c.cancel(p.ticket)
+c.cancel(p.ticket)                                # returns the order that was deleted
 
 c.close_by(a.ticket, b.ticket)                    # close one position against an opposite one (hedged accounts)
 c.close_all_by("EURUSDm")                         # ... every opposite pair of the symbol
@@ -165,7 +185,7 @@ remainder of the position may carry a new ticket: read `positions()`.
 ## Sizing and risk
 
 ```python
-r = c.lots_for_risk("EURUSDm", entry_price=1.1000, stop_price=1.0950, risk_amount=50.0)
+r = c.lots_for_risk("EURUSDm", entry_price=1.1000, stop_price=1.0950, risk_amount=50.0, side="buy")
 for w in r.warnings:
     print("warning:", w)                  # ok can still be True with a caveat (the broker's minimum volume risks more)
 if r.ok:
@@ -224,8 +244,8 @@ restored, cached snapshots are not. `disconnect()` is final: it also stops a rec
 | API key | `api_key=` | `WMT4API_KEY` (then `WMTAPI_KEY`) |
 | Licence service URL (leave at its default) | `token_url=` | `WMT4API_TOKEN_URL` |
 | Core library (only if you do not use a wheel that carries it) | `dll_path=` | `WMT4API_DLL` |
-| Timeouts (seconds, each > 0) | `connect_timeout` (one attempt on one server), `token_timeout`, `trade_timeout` (≥ 1), `quote_timeout` / `history_timeout` / `bars_timeout` (the defaults of `quote`, `history`, `bars`), `no_message_timeout` | — |
-| Reconnect | `auto_reconnect`, `reconnect_backoff`, `reconnect_max_attempts`, `servers=` | — |
+| Timeouts (seconds, each > 0) | `connect_timeout` (one attempt on one server; default 6), `token_timeout` (10), `trade_timeout` (30; ≥ 1), `quote_timeout` (5) / `history_timeout` (30) / `bars_timeout` (30) — the defaults of `quote`, `history`, `bars`, `no_message_timeout` (30; ≥ 10, or 0 for off) | — |
+| Reconnect | `auto_reconnect`, `reconnect_backoff` (3, doubling up to `reconnect_max_backoff`, 30), `reconnect_max_attempts` (0 = no limit), `servers=` | — |
 | Orders | `placed_type=` (`manual`, `expert`, `dealer` …), `comment_encoding=` (default `latin-1`) | — |
 | .NET runtime location | — | `DOTNET_ROOT` |
 
@@ -245,7 +265,15 @@ pmt4api.enable_core_logging()          # the core's own messages -> logging.getL
 
 `load_servers_ini(path_or_bytes)` / `save_servers_ini(records)` read and write a terminal's `servers.ini`.
 `python -m pmt4api` prints what is installed and whether it works here (`--connect` also reads an account, using
-`PMT4_LOGIN`, `PMT4_PASSWORD`, `PMT4_HOST`); the output holds no secrets.
+`PMT4_LOGIN`, `PMT4_PASSWORD`, `PMT4_HOST` — a bare host, or `host:port`, or the port in `PMT4_PORT`); the output holds
+no secrets.
+
+## What a closed order says about why
+
+An MT4 server pushes the same `PositionClose` update for a stop-loss, a take-profit and a close you asked for; the
+reason is in the order's `comment`, which the server suffixes with `[sl]` or `[tp]` for a stop or a take-profit hit.
+Pressing Ctrl+C while `connect()` is dialling is honoured when the dial ends (up to `connect_timeout`), not at once.
+`token_timeout` bounds one licence request; a failed request is tried again and a connect tries each server of the list, so a connect to an unreachable licence service can wait several times that (about 44 s at the default 10).
 
 ## Errors
 

{pmt4api-1.0.0 → pmt4api-1.1.2}/src/pmt4api/__init__.py

@@ -17,7 +17,7 @@ from .models import (AccountInfo, AccountSummary, ConnectEvent, EquityPoint, Lot
                      OrderUpdate, Quote, ServerRecord, SymbolGroup, SymbolInfo)
 from .servers import load_servers_ini, save_servers_ini
 
-__version__ = "1.0.0"
+__version__ = "1.1.2"
 
 __all__ = [
     "Client",

{pmt4api-1.0.0 → pmt4api-1.1.2}/src/pmt4api/__main__.py

@@ -62,6 +62,10 @@ def main(argv: Optional[List[str]] = None) -> int:
             print("connect SKIPPED: environment variable %s is not set" % e)
             return 0
         port = int(os.environ.get("PMT4_PORT", "443"))
+        if ":" in host:                      # an account file lists "host:port"
+            host, _, given = host.rpartition(":")
+            if given.isdigit():
+                port = int(given)
         try:
             with Client(login, password, host, port, connect_timeout=45) as live:
                 a = live.account()

{pmt4api-1.0.0 → pmt4api-1.1.2}/src/pmt4api/_base.py

@@ -11,6 +11,12 @@ class _Base:
     _api: Any      # the core's client object (MT5API / MT4API)
     _core: Any     # the core's namespace (types and enums)
 
+    def _stop_events(self) -> None:
+        """End the callback thread (it restarts by itself with the next event): a closed client keeps no thread."""
+        d = getattr(self, "_dispatch", None)
+        if d is not None:
+            d.stop()
+
     def _require_connected(self) -> None:
         if not self._api.Connected:
             raise NotConnectedError("not connected; call connect() first")

{pmt4api-1.0.0 → pmt4api-1.1.2}/src/pmt4api/_coverage.py

@@ -47,6 +47,7 @@ COVERAGE: Dict[str, str] = {
     "TradeTimeout": "Client(trade_timeout)",
     "AutoReconnect": "Client(auto_reconnect)",
     "ReconnectBackoffMs": "Client(reconnect_backoff)",
+    "ReconnectMaxBackoffMs": "Client(reconnect_max_backoff)",
     "ReconnectMaxAttempts": "Client(reconnect_max_attempts)",
     "Encoding": "Client(comment_encoding)",
     "PlacedType": "Client(placed_type)",

{pmt4api-1.0.0 → pmt4api-1.1.2}/src/pmt4api/_events.py

@@ -7,6 +7,7 @@ to a callback that fell too far behind.
 from __future__ import annotations
 
 import logging
+import weakref
 from typing import Any, AsyncIterator, Callable, Iterator, Optional
 
 from ._base import _Base
@@ -59,6 +60,7 @@ class _EventsMixin(_Base):
             d = getattr(self, "_dispatch", None)
             if d is None:
                 d = self._dispatch = _Dispatcher()
+                weakref.finalize(self, d.stop)       # a client that is dropped without disconnect() leaves no thread
             return d
 
     def _wanted(self, symbols: Any) -> Any:

{pmt4api-1.0.0 → pmt4api-1.1.2}/src/pmt4api/_risk.py

@@ -15,16 +15,28 @@ class _RiskMixin(_Base):
     def lots_for_risk(self, symbol: str, entry_price: float, stop_price: float, risk_amount: float, *,
                       lot_step: Optional[float] = None, min_lot: Optional[float] = None,
                       max_ratio: Optional[float] = None, max_equity_share: Optional[float] = None,
-                      max_lot: Optional[float] = None) -> LotSizing:
+                      max_lot: Optional[float] = None, side: Optional[str] = None) -> LotSizing:
         """The volume that loses ``risk_amount`` (account currency) if ``stop_price`` is hit, with the evidence.
 
         The value of a price unit comes from :meth:`tick_value` and the broker's step / minimum / maximum volume from
         the account's own group (pass one to override it); a size that cannot be justified is refused, not guessed.
         The volume is rounded **down** to the step. Check ``ok``: when false, ``lots`` is 0 and ``reason`` says which
-        check failed. Amounts are in the currency the account reports (no cent-account scaling is applied: check the
+        check failed. Give ``side`` (``"buy"`` or ``"sell"``) and a stop on the wrong side of the entry is refused instead
+        of sized by its distance. Amounts are in the currency the account reports (no cent-account scaling is applied: check the
         first result against your terminal).
         """
         self._require_connected()
+        if side is not None:
+            key = str(side).strip().lower()
+            if key not in ("buy", "sell"):
+                raise ValueError("side must be 'buy' or 'sell'")
+            wrong = (stop_price >= entry_price) if key == "buy" else (stop_price <= entry_price)
+            if wrong:                                 # a stop on the wrong side of the entry is not a stop
+                return LotSizing(ok=False, lots=0.0, expected_loss_at_stop=0.0, risk_requested=float(risk_amount),
+                                 minimum_trade_cost=0.0, ratio=0.0,
+                                 reason="a %s needs its stop %s the entry price (entry %g, stop %g)"
+                                        % (key, "below" if key == "buy" else "above", entry_price, stop_price),
+                                 warnings=())
         kwargs = {}
         for key, value in (("lotStep", lot_step), ("minLot", min_lot), ("maxRatio", max_ratio),
                            ("maxEquityShare", max_equity_share), ("maxLot", max_lot)):

{pmt4api-1.0.0 → pmt4api-1.1.2}/src/pmt4api/_runtime.py

@@ -5,6 +5,7 @@ import glob
 import importlib
 import os
 import shutil
+import struct
 import sys
 import threading
 from pathlib import Path
@@ -17,8 +18,25 @@ ENV_DLL = "WMT4API_DLL"
 
 _NAMESPACE = "wmt4api"      # the .NET namespace of the core; NOT the name of this Python package
 _PKG = Path(__file__).resolve().parent
+_BITNESS_HINT = (" This is a 32-bit Python: it needs the 32-bit (x86) .NET runtime, and 64-bit Python with the 64-bit "
+                 "runtime is the supported combination.")
 _BUNDLED_RUNTIME = _PKG / "_dotnet"     # present in the platform wheels: host/fxr + shared/Microsoft.NETCore.App
-_lock = threading.Lock()
+
+
+def _process_lock() -> "threading.RLock":
+    """ONE lock for every pmt*api package in the process. Each package has its own copy of this module, but the .NET
+    runtime is one per process: two packages starting it from two threads at once raced inside pythonnet. The lock
+    lives in ``sys.modules`` under a fixed name, which both copies see."""
+    holder = sys.modules.get("_pmt_runtime_lock")
+    if holder is None:
+        import types
+        fresh = types.ModuleType("_pmt_runtime_lock")
+        fresh.lock = threading.RLock()                   # type: ignore[attr-defined]
+        holder = sys.modules.setdefault("_pmt_runtime_lock", fresh)
+    return holder.lock                                   # type: ignore[attr-defined]
+
+
+_lock = _process_lock()
 _core = None
 _dll: Optional[Path] = None
 
@@ -137,7 +155,11 @@ def load(dll_path=None):
             _load("coreclr")
             import clr  # noqa: F401  (provided by pythonnet)
         except Exception as e:  # noqa: BLE001 — anything here means the runtime could not start
-            raise RuntimeNotFoundError("could not start the .NET runtime: %s" % e) from e
+            raise RuntimeNotFoundError(
+                "could not start the .NET runtime. The core needs the .NET 8 (or later) runtime, Microsoft.NETCore.App: "
+                "install it from https://dotnet.microsoft.com/download/dotnet/8.0 (`dotnet --list-runtimes` lists what "
+                "this machine has) or point DOTNET_ROOT at a folder that holds it.%s Detail: %s: %s"
+                % (_BITNESS_HINT if struct.calcsize("P") == 4 else "", type(e).__name__, str(e)[:240])) from e
         import clr as _clr
         from System.Reflection import Assembly      # available once the runtime is up
         try:

{pmt4api-1.0.0 → pmt4api-1.1.2}/src/pmt4api/_session.py

@@ -53,6 +53,8 @@ class _SessionMixin(_Base):
         except Exception as exc:  # noqa: BLE001
             if type(exc).__name__ != "NullReferenceException":      # never connected: nothing to close
                 raise
+        finally:
+            self._stop_events()                  # the callback thread ends once what is queued is delivered
 
     @property
     def connected(self) -> bool:

{pmt4api-1.0.0 → pmt4api-1.1.2}/src/pmt4api/_streams.py

@@ -26,21 +26,35 @@ log = logging.getLogger(_PACKAGE)
 EVENT_QUEUE = 20000
 
 
+_STOP = object()          # put on the dispatcher's queue: end the thread once everything queued before it is delivered
+
+
 class _Dispatcher:
-    """One thread that runs a client's callbacks in arrival order."""
+    """One thread that runs a client's callbacks in arrival order.
+
+    The thread exists only while there is something to deliver or the client is connected: it is started by the first
+    event, ended by :meth:`stop` (a client's ``disconnect()``, or the client being garbage-collected), and started again
+    by the next event. A client that is dropped therefore leaves no thread behind."""
 
     def __init__(self) -> None:
-        self._q: "queue.Queue[Tuple[Callable[[Any], None], Any, str]]" = queue.Queue(maxsize=EVENT_QUEUE)
+        self._q: "queue.Queue[Any]" = queue.Queue(maxsize=EVENT_QUEUE)
         self.dropped = 0
         self._count_lock = threading.Lock()
-        self._thread = threading.Thread(target=self._run, name=_PACKAGE + "-events", daemon=True)
-        self._thread.start()
+        self._thread_lock = threading.Lock()
+        self._thread: Optional[threading.Thread] = None
+
+    def _ensure_thread(self) -> None:
+        with self._thread_lock:
+            if self._thread is None:
+                t = threading.Thread(target=self._run, name=_PACKAGE + "-events", daemon=True)
+                self._thread = t
+                t.start()
 
     def submit(self, fn: Callable[[Any], None], arg: Any, event: str) -> None:
         while True:
             try:
                 self._q.put_nowait((fn, arg, event))
-                return
+                break
             except queue.Full:
                 try:
                     self._q.get_nowait()
@@ -51,10 +65,29 @@ class _Dispatcher:
                     total = self.dropped
                 if total == 1 or total % 1000 == 0:
                     log.warning("event queue full: %d event(s) dropped so far; a callback is too slow", total)
+        self._ensure_thread()
+
+    def stop(self) -> None:
+        """End the thread after it has delivered what is queued. Safe to call at any time and more than once; events
+        that arrive afterwards start a new thread."""
+        with self._thread_lock:
+            running = self._thread is not None
+        if running:
+            try:
+                self._q.put_nowait(_STOP)
+            except queue.Full:       # a full queue means the thread is busy: it ends when it next finds the queue empty
+                pass
 
     def _run(self) -> None:
         while True:
-            fn, arg, event = self._q.get()
+            item = self._q.get()
+            if item is _STOP:
+                with self._thread_lock:
+                    if self._q.empty():          # nothing arrived behind the marker: the thread can end
+                        self._thread = None
+                        return
+                continue                         # events were queued after stop(): keep going, they need delivering
+            fn, arg, event = item
             try:
                 fn(arg)
             except Exception:  # noqa: BLE001 — keep the dispatcher alive

{pmt4api-1.0.0 → pmt4api-1.1.2}/src/pmt4api/_trading.py

@@ -243,11 +243,13 @@ class _TradingMixin(_Base):
         return self._confirmed(self._api.OrderClose(str(o.Symbol), int(o.Ticket), amount, px, int(slippage)))
 
     @translated
-    def cancel(self, ticket: int) -> None:
-        """Delete a pending order."""
+    def cancel(self, ticket: int) -> Order:
+        """Delete a pending order. Returns the order that was deleted, as it stood."""
         self._require_connected()
         o = self._open_pending(ticket)
+        gone = Order._from_core(o)
         self._api.OrderCancel(int(o.Ticket), o.Type, str(o.Symbol), float(o.Lots), float(o.OpenPrice))
+        return gone
 
     @translated
     def close_by(self, ticket: int, opposite_ticket: int) -> None:
@@ -371,7 +373,7 @@ class _TradingMixin(_Base):
         """Awaitable :meth:`close`."""
         return await self._run(self.close, *args, **kwargs)
 
-    async def acancel(self, *args: Any, **kwargs: Any) -> None:
+    async def acancel(self, *args: Any, **kwargs: Any) -> Order:
         """Awaitable :meth:`cancel`."""
         return await self._run(self.cancel, *args, **kwargs)
 

{pmt4api-1.0.0 → pmt4api-1.1.2}/src/pmt4api/_util.py

@@ -4,12 +4,14 @@ from __future__ import annotations
 import functools
 import math
 from datetime import datetime
-from typing import Any, Callable, Optional
+from typing import Any, Callable, Optional, TypeVar, cast
 
 from .errors import WmtError, translate
 
+F = TypeVar("F", bound=Callable[..., Any])
 
-def translated(fn: Callable) -> Callable:
+
+def translated(fn: F) -> F:
     """Re-raise the core's exceptions as the pmt4api hierarchy (the core exception stays as ``__cause__``)."""
     @functools.wraps(fn)
     def wrapper(*args: Any, **kwargs: Any) -> Any:
@@ -22,7 +24,7 @@ def translated(fn: Callable) -> Callable:
             if mapped is None:
                 raise
             raise mapped from exc
-    return wrapper
+    return cast(F, wrapper)       # the same signature, so type checkers and IDEs keep the real parameters
 
 
 def to_core_time(value: datetime) -> Any:

{pmt4api-1.0.0 → pmt4api-1.1.2}/src/pmt4api/bars.py

@@ -60,3 +60,10 @@ class QuoteHistoryEvent:
     @classmethod
     def _from_core(cls, e: Any) -> "QuoteHistoryEvent":
         return cls(symbol=str(e.Symbol), timeframe=str(e.Timeframe), bars=tuple(Bar._from_core(b) for b in (e.Bars or ())))
+
+
+Bar.FIELD_DOC = {
+    "time": "the start of the period, broker server time",
+    "open": "first price of the period", "high": "highest price", "low": "lowest price", "close": "last price",
+    "volume": "the number of ticks in the period (MT4 reports tick volume only)",
+}

{pmt4api-1.0.0 → pmt4api-1.1.2}/src/pmt4api/client.py

@@ -68,11 +68,13 @@ class Client(_SessionMixin, _MarketMixin, _AccountMixin, _RiskMixin, _TradingMix
     seconds, so a longer silence means the link stopped carrying traffic). Every other timeout must be positive; the
     quote, history and bars timeouts are the defaults of :meth:`quote`, :meth:`history` and :meth:`bars`. The
     handshake with the broker has its own fixed 30 s limit, whatever ``connect_timeout`` says (that one bounds the
-    TCP dial of each server).
+    TCP dial of each server). **Defaults:** ``connect_timeout`` 6 s, ``token_timeout`` 10 s, ``trade_timeout`` 30 s,
+    ``quote_timeout`` 5 s, ``history_timeout`` 30 s, ``bars_timeout`` 30 s, ``no_message_timeout`` 30 s,
+    ``reconnect_backoff`` 3 s (it doubles up to ``reconnect_max_backoff``, 30 s).
 
     Reconnecting: ``auto_reconnect=True`` turns on the core's watchdog (exponential backoff, failover across the
     primary server, ``servers`` and the broker's published list, re-subscription); tune it with ``reconnect_backoff``
-    (seconds) and ``reconnect_max_attempts`` (0 = until reconnected or ``disconnect()``). Do not poll ``connected``
+    and ``reconnect_max_backoff`` (seconds) and ``reconnect_max_attempts`` (0 = until reconnected or ``disconnect()``). Do not poll ``connected``
     and call ``connect()`` in a loop. ``servers`` are extra ``(host, port)`` access servers to fall back to.
 
     ``comment_encoding`` is the codepage order comments are written in (default ``latin-1``); ``placed_type``
@@ -88,7 +90,7 @@ class Client(_SessionMixin, _MarketMixin, _AccountMixin, _RiskMixin, _TradingMix
                  history_timeout: Optional[float] = None, bars_timeout: Optional[float] = None,
                  no_message_timeout: Optional[float] = None,
                  auto_reconnect: bool = False, reconnect_backoff: Optional[float] = None,
-                 reconnect_max_attempts: Optional[int] = None,
+                 reconnect_max_backoff: Optional[float] = None, reconnect_max_attempts: Optional[int] = None,
                  servers: Optional[Sequence[Tuple[str, int]]] = None, comment_encoding: str = "latin-1",
                  placed_type: Optional[str] = None):
         core = _runtime.load(dll_path)
@@ -108,7 +110,8 @@ class Client(_SessionMixin, _MarketMixin, _AccountMixin, _RiskMixin, _TradingMix
             api.TokenServiceUrl = token_url
         for attr, value in (("ConnectTimeout", connect_timeout), ("TokenServiceTimeout", token_timeout),
                             ("GetQuoteTimeoutMs", quote_timeout), ("DownloadOrderHistoryTimeoutMs", history_timeout),
-                            ("DownloadQuoteHistoryTimeout", bars_timeout), ("ReconnectBackoffMs", reconnect_backoff)):
+                            ("DownloadQuoteHistoryTimeout", bars_timeout), ("ReconnectBackoffMs", reconnect_backoff),
+                            ("ReconnectMaxBackoffMs", reconnect_max_backoff)):
             ms = seconds_to_ms(value, attr)
             if ms is not None:
                 setattr(api, attr, ms)

{pmt4api-1.0.0 → pmt4api-1.1.2}/src/pmt4api/docs/API.md

@@ -5,7 +5,7 @@ Generated from the code (`tools/gen_docs.py`); do not edit by hand. Times are na
 ## Constructing a client
 
 ```python
-Client(login, password, host, port=443, *, api_key=None, token_url=None, dll_path=None, connect_timeout=None, token_timeout=None, trade_timeout=None, quote_timeout=None, history_timeout=None, bars_timeout=None, no_message_timeout=None, auto_reconnect=False, reconnect_backoff=None, reconnect_max_attempts=None, servers=None, comment_encoding='latin-1', placed_type=None)
+Client(login, password, host, port=443, *, api_key=None, token_url=None, dll_path=None, connect_timeout=None, token_timeout=None, trade_timeout=None, quote_timeout=None, history_timeout=None, bars_timeout=None, no_message_timeout=None, auto_reconnect=False, reconnect_backoff=None, reconnect_max_backoff=None, reconnect_max_attempts=None, servers=None, comment_encoding='latin-1', placed_type=None)
 ```
 
 A connection to one MetaTrader 4 account through the licensed core.
@@ -24,11 +24,13 @@ declared dead and closed: default 30 s, at least 10 s, `0` switches it off; the
 seconds, so a longer silence means the link stopped carrying traffic). Every other timeout must be positive; the
 quote, history and bars timeouts are the defaults of `quote`, `history` and `bars`. The
 handshake with the broker has its own fixed 30 s limit, whatever `connect_timeout` says (that one bounds the
-TCP dial of each server).
+TCP dial of each server). **Defaults:** `connect_timeout` 6 s, `token_timeout` 10 s, `trade_timeout` 30 s,
+`quote_timeout` 5 s, `history_timeout` 30 s, `bars_timeout` 30 s, `no_message_timeout` 30 s,
+`reconnect_backoff` 3 s (it doubles up to `reconnect_max_backoff`, 30 s).
 
 Reconnecting: `auto_reconnect=True` turns on the core's watchdog (exponential backoff, failover across the
 primary server, `servers` and the broker's published list, re-subscription); tune it with `reconnect_backoff`
-(seconds) and `reconnect_max_attempts` (0 = until reconnected or `disconnect()`). Do not poll `connected`
+and `reconnect_max_backoff` (seconds) and `reconnect_max_attempts` (0 = until reconnected or `disconnect()`). Do not poll `connected`
 and call `connect()` in a loop. `servers` are extra `(host, port)` access servers to fall back to.
 
 `comment_encoding` is the codepage order comments are written in (default `latin-1`); `placed_type`
@@ -336,14 +338,15 @@ Blocks up to `quote_timeout` per symbol.
 
 ## Sizing and risk
 
-#### `lots_for_risk(symbol, entry_price, stop_price, risk_amount, *, lot_step=None, min_lot=None, max_ratio=None, max_equity_share=None, max_lot=None)`
+#### `lots_for_risk(symbol, entry_price, stop_price, risk_amount, *, lot_step=None, min_lot=None, max_ratio=None, max_equity_share=None, max_lot=None, side=None)`
 
 The volume that loses `risk_amount` (account currency) if `stop_price` is hit, with the evidence.
 
 The value of a price unit comes from `tick_value` and the broker's step / minimum / maximum volume from
 the account's own group (pass one to override it); a size that cannot be justified is refused, not guessed.
 The volume is rounded **down** to the step. Check `ok`: when false, `lots` is 0 and `reason` says which
-check failed. Amounts are in the currency the account reports (no cent-account scaling is applied: check the
+check failed. Give `side` (`"buy"` or `"sell"`) and a stop on the wrong side of the entry is refused instead
+of sized by its distance. Amounts are in the currency the account reports (no cent-account scaling is applied: check the
 first result against your terminal).
 
 #### `order_profit(symbol, open_price, close_price, lots, buy=True)`
@@ -407,7 +410,7 @@ through `on_order_progress` (and `on_order_update`).
 
 #### `cancel(ticket)`
 
-Delete a pending order.
+Delete a pending order. Returns the order that was deleted, as it stood.
 
 #### `cancel_async(ticket)`
 
@@ -566,13 +569,38 @@ A list of bars is indexed by its `time`; anything else keeps a plain integer ind
 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.
 
-Fields: `symbol`, `bid`, `ask`, `time`, `high`, `low`
+| Field | Type | Meaning |
+|---|---|---|
+| `symbol` | `str` | the symbol as the broker names it |
+| `bid` | `float` | the price a sell is made at |
+| `ask` | `float` | the price a buy is made at |
+| `time` | `Optional[datetime]` | the server time of the tick: how old the price is |
+| `high` | `Optional[float]` | the session's high once the server has sent it (`None` before) |
+| `low` | `Optional[float]` | the session's low once the server has sent it (`None` before) |
 
 #### `SymbolInfo`
 
 A symbol's specification and trading rules, as the server publishes them.
 
-Fields: `name`, `digits`, `point`, `currency`, `profit_mode`, `contract_size`, `margin_divider`, `tick_size`, `execution`, `security_index`, `min_lots`, `max_lots`, `lots_step`, `code`, `raw_tick_value`, `raw_bid_tick_value`, `raw_ask_tick_value`
+| Field | Type | Meaning |
+|---|---|---|
+| `name` | `str` | the symbol as the broker names it |
+| `digits` | `int` | the price digits |
+| `point` | `float` | the smallest price step: 10 to the power of −digits |
+| `currency` | `str` | the instrument's own currency: the base currency of a forex pair (EUR for EURUSD); profit is realised in `profit_currency` |
+| `profit_mode` | `str` | how profit is calculated: Forex, CFD or Futures |
+| `contract_size` | `float` | units of the instrument per 1.0 lot |
+| `margin_divider` | `float` | the divider of the margin formula of a CFD symbol |
+| `tick_size` | `float` | the smallest price change the server quotes |
+| `execution` | `str` | how orders execute: Request, Instant, Market or Exchange |
+| `security_index` | `int` | the account group's security (symbol class) the volume rules are keyed on |
+| `min_lots` | `float` | the smallest volume |
+| `max_lots` | `float` | the largest volume |
+| `lots_step` | `float` | the volume step |
+| `code` | `int` | the feed code the server uses for the symbol |
+| `raw_tick_value` | `float` | the server's own tick value (brokers often report 0: use `Client.tick_value`) |
+| `raw_bid_tick_value` | `float` | the server's tick value for a sell (often 0) |
+| `raw_ask_tick_value` | `float` | the server's tick value for a buy (often 0) |
 
 #### `SymbolGroup`
 
@@ -587,7 +615,24 @@ are derived on the client from the live quotes (the server does not push them),
 `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.
 
-Fields: `login`, `name`, `company`, `group`, `currency`, `leverage`, `balance`, `credit`, `equity`, `profit`, `margin`, `free_margin`, `margin_level`, `account_type`, `is_investor`, `priced_from`
+| Field | Type | Meaning |
+|---|---|---|
+| `login` | `int` | the account number |
+| `name` | `str` | the account holder's name as the broker holds it (personal data: keep it out of logs) |
+| `company` | `str` | the broker's company name |
+| `group` | `str` | the account's group on the server |
+| `currency` | `str` | the deposit currency; every money figure below is in it |
+| `leverage` | `int` | the N in 1:N |
+| `balance` | `float` | closed-trade funds, floating profit excluded; it moves with every close and every deposit or withdrawal the session sees |
+| `credit` | `float` | credit the broker granted |
+| `equity` | `float` | balance + credit + floating profit (swap and commission of the open positions included) |
+| `profit` | `float` | floating profit of the open positions including swap and commission |
+| `margin` | `float` | the margin the open positions hold, derived on the client as the terminal does |
+| `free_margin` | `float` | equity − margin |
+| `margin_level` | `float` | equity ÷ margin × 100; 0 when no margin is used |
+| `account_type` | `str` | the server's class of the account: Real, Demo or Contest |
+| `is_investor` | `bool` | the login is the read-only investor password |
+| `priced_from` | `Optional[datetime]` | the server time of the oldest quote the floating figures used (old while the market is open means the feed is not delivering) |
 
 #### `AccountSummary`
 
@@ -614,13 +659,40 @@ Fields: `ok`, `lots`, `expected_loss_at_stop`, `risk_requested`, `minimum_trade_
 
 One MT4 order: an open position, a pending order, a closed order of the history, or a balance / credit entry.
 
-Fields: `ticket`, `symbol`, `order_type`, `lots`, `open_time`, `open_price`, `stop_loss`, `take_profit`, `close_time`, `close_price`, `expiration`, `magic`, `swap`, `commission`, `comment`, `profit`, `rate_open`, `rate_close`, `rate_margin`
+| Field | Type | Meaning |
+|---|---|---|
+| `ticket` | `int` | the order's ticket (a partial close leaves the remainder under a new ticket) |
+| `symbol` | `str` | the symbol as the broker names it |
+| `order_type` | `str` | `Buy`, `Sell` (a position), `BuyLimit`, `SellLimit`, `BuyStop`, `SellStop` (pending), or `Balance` / `Credit` for a capital entry |
+| `lots` | `float` | the volume in lots |
+| `open_time` | `Optional[datetime]` | when it opened or was placed, broker server time |
+| `open_price` | `float` | the price the position opened at, or a pending order's price |
+| `stop_loss` | `float` | stop-loss price (0 = none) |
+| `take_profit` | `float` | take-profit price (0 = none) |
+| `close_time` | `Optional[datetime]` | when it closed, broker server time (`None` while open) |
+| `close_price` | `float` | the price it closed at; meaningful on a closed order only |
+| `expiration` | `Optional[datetime]` | when a pending order expires (`None` = good till cancelled) |
+| `magic` | `int` | always 0: the core does not carry a magic number; tag orders with `comment` |
+| `swap` | `float` | swap in the deposit currency |
+| `commission` | `float` | commission in the deposit currency (charged when the position closes) |
+| `comment` | `str` | the order's comment (ASCII, 31 characters at most) |
+| `profit` | `float` | profit in the deposit currency before swap and commission |
+| `rate_open` | `float` | the conversion rate at open, as the server reports it |
+| `rate_close` | `float` | the conversion rate at close, as the server reports it |
+| `rate_margin` | `float` | the conversion rate used for the margin, as the server reports it |
 
 #### `Bar`
 
 Bar(time: 'datetime', open: 'float', high: 'float', low: 'float', close: 'float', volume: 'float')
 
-Fields: `time`, `open`, `high`, `low`, `close`, `volume`
+| Field | Type | Meaning |
+|---|---|---|
+| `time` | `datetime` | the start of the period, broker server time |
+| `open` | `float` | first price of the period |
+| `high` | `float` | highest price |
+| `low` | `float` | lowest price |
+| `close` | `float` | last price |
+| `volume` | `float` | the number of ticks in the period (MT4 reports tick volume only) |
 
 #### `OrderUpdate`
 

{pmt4api-1.0.0 → pmt4api-1.1.2}/src/pmt4api/docs/FROM-CSHARP.md

@@ -79,6 +79,7 @@ Every public member of the C# `MT4API` and `OrderClient` classes and where it we
 | `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)` |  |
+| `ReconnectMaxBackoffMs` | `Client(reconnect_max_backoff)` |  |
 | `RequiredMargin` | `Client.required_margin` |  |
 | `SaveServersIni` | `pmt4api.save_servers_ini` |  |
 | `Servers` | `Client.servers` | give `servers=[(host, port), ...]` to the constructor or call `add_server` |

{pmt4api-1.0.0 → pmt4api-1.1.2}/src/pmt4api/errors.py

@@ -163,6 +163,14 @@ _BARE_MESSAGES = (
 _WRAPPERS = ("AggregateException", "TargetInvocationException")
 
 
+def _python_words(text: str) -> str:
+    """The core words its configuration for a C# program; say it as this package takes it."""
+    return (text.replace("set MT4API.ApiKey or the WMT4API_KEY environment variable",
+                         "pass api_key= to Client(...) or set the WMT4API_KEY environment variable")
+                .replace("set MT4API.TokenServiceUrl or the WMT4API_TOKEN_URL environment variable",
+                         "pass token_url= to Client(...) or set the WMT4API_TOKEN_URL environment variable"))
+
+
 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:
@@ -189,6 +197,7 @@ def translate(exc: BaseException) -> Optional[WmtError]:
             continue
         message = str(getattr(exc, "Message", None) or exc)
         if kind == "license":
+            message = _python_words(message)
             reason = getattr(exc, "Reason", None)
             status = getattr(exc, "HttpStatus", None)
             detail = getattr(exc, "ServerError", None)
@@ -209,7 +218,10 @@ def translate(exc: BaseException) -> Optional[WmtError]:
             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)
+            name = code_name(value)
+            if value is not None and name and ("(code %d)" % value) in message:
+                message = message.replace("(code %d)" % value, "(code %d: %s)" % (value, name))
+            return cls(message, name, value)
         if kind == "timeout":
             return RequestTimeout(message)
         if kind == "cancelled":

{pmt4api-1.0.0 → pmt4api-1.1.2}/src/pmt4api/models.py

@@ -52,6 +52,11 @@ def _unset_if_zero(value: Any) -> Optional[float]:
 
 # ---- market data ------------------------------------------------------------------------------------------------
 
+
+def _m(value: Any) -> float:
+    """A money amount without the binary noise of the core's sums (1.3900000000000001 becomes 1.39)."""
+    return round(float(value), 8)
+
 @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``
@@ -280,8 +285,8 @@ class 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),
+                   expiration=_time(o.ExpirationTime), magic=int(o.ExpertId), swap=_m(o.Swap),
+                   commission=_m(o.Commission), comment=str(o.Comment or ""), profit=_m(o.Profit),
                    rate_open=float(o.RateOpen), rate_close=float(o.RateClose), rate_margin=float(o.RateMargin))
 
 
@@ -335,3 +340,74 @@ class 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 ())))
+
+
+# ---- what each field means (rendered into docs/API.md by tools/gen_docs.py) ------------------------------------------
+AccountInfo.FIELD_DOC = {
+    "login": "the account number",
+    "name": "the account holder's name as the broker holds it (personal data: keep it out of logs)",
+    "company": "the broker's company name",
+    "group": "the account's group on the server",
+    "currency": "the deposit currency; every money figure below is in it",
+    "leverage": "the N in 1:N",
+    "balance": "closed-trade funds, floating profit excluded; it moves with every close and every deposit or "
+               "withdrawal the session sees",
+    "credit": "credit the broker granted",
+    "equity": "balance + credit + floating profit (swap and commission of the open positions included)",
+    "profit": "floating profit of the open positions including swap and commission",
+    "margin": "the margin the open positions hold, derived on the client as the terminal does",
+    "free_margin": "equity − margin",
+    "margin_level": "equity ÷ margin × 100; 0 when no margin is used",
+    "account_type": "the server's class of the account: Real, Demo or Contest",
+    "is_investor": "the login is the read-only investor password",
+    "priced_from": "the server time of the oldest quote the floating figures used (old while the market is open means "
+                   "the feed is not delivering)",
+}
+Order.FIELD_DOC = {
+    "ticket": "the order's ticket (a partial close leaves the remainder under a new ticket)",
+    "symbol": "the symbol as the broker names it",
+    "order_type": "`Buy`, `Sell` (a position), `BuyLimit`, `SellLimit`, `BuyStop`, `SellStop` (pending), or `Balance` / "
+                  "`Credit` for a capital entry",
+    "lots": "the volume in lots",
+    "open_time": "when it opened or was placed, broker server time",
+    "open_price": "the price the position opened at, or a pending order's price",
+    "stop_loss": "stop-loss price (0 = none)",
+    "take_profit": "take-profit price (0 = none)",
+    "close_time": "when it closed, broker server time (`None` while open)",
+    "close_price": "the price it closed at; meaningful on a closed order only",
+    "expiration": "when a pending order expires (`None` = good till cancelled)",
+    "magic": "always 0: the core does not carry a magic number; tag orders with `comment`",
+    "swap": "swap in the deposit currency",
+    "commission": "commission in the deposit currency (charged when the position closes)",
+    "comment": "the order's comment (ASCII, 31 characters at most)",
+    "profit": "profit in the deposit currency before swap and commission",
+    "rate_open": "the conversion rate at open, as the server reports it",
+    "rate_close": "the conversion rate at close, as the server reports it",
+    "rate_margin": "the conversion rate used for the margin, as the server reports it",
+}
+SymbolInfo.FIELD_DOC = {
+    "name": "the symbol as the broker names it",
+    "digits": "the price digits",
+    "point": "the smallest price step: 10 to the power of −digits",
+    "currency": "the instrument's own currency: the base currency of a forex pair (EUR for EURUSD); profit is "
+                "realised in `profit_currency`",
+    "profit_mode": "how profit is calculated: Forex, CFD or Futures",
+    "contract_size": "units of the instrument per 1.0 lot",
+    "margin_divider": "the divider of the margin formula of a CFD symbol",
+    "tick_size": "the smallest price change the server quotes",
+    "execution": "how orders execute: Request, Instant, Market or Exchange",
+    "security_index": "the account group's security (symbol class) the volume rules are keyed on",
+    "min_lots": "the smallest volume", "max_lots": "the largest volume", "lots_step": "the volume step",
+    "code": "the feed code the server uses for the symbol",
+    "raw_tick_value": "the server's own tick value (brokers often report 0: use `Client.tick_value`)",
+    "raw_bid_tick_value": "the server's tick value for a sell (often 0)",
+    "raw_ask_tick_value": "the server's tick value for a buy (often 0)",
+}
+Quote.FIELD_DOC = {
+    "symbol": "the symbol as the broker names it",
+    "bid": "the price a sell is made at",
+    "ask": "the price a buy is made at",
+    "time": "the server time of the tick: how old the price is",
+    "high": "the session's high once the server has sent it (`None` before)",
+    "low": "the session's low once the server has sent it (`None` before)",
+}

pmt4api-1.0.0/CHANGELOG.md

@@ -1,17 +0,0 @@
-# Changelog — pmt4api
-
-## [1.0.0] — 2026-10-12
-First release: the complete Python interface to wmt4api 3.2.0 (the MetaTrader 4 client library).
-
-- Every public member and type of the C# `MT4API` / `OrderClient` classes is mapped to a Python counterpart, or has a
-  stated reason for not having one (`pmt4api.COVERAGE`, `pmt4api.TYPES`; a test fails when the core gains an
-  unaccounted member).
-- Market data (symbols, quotes, bars on the nine MT4 timeframes with paging), account, sizing and risk, order entry
-  (market, pending, modify, partial close, close-by, close-all-by, cancel; synchronous, with request ids and progress
-  events, and awaitable), history, summary and equity curve.
-- Callbacks, sync and async iterators, one ordered dispatcher thread per client, with back-pressure accounting.
-- A small error hierarchy; the MT4 trade-return codes by name; requotes carry the new prices.
-- `auto_reconnect`, `servers=` failover, a silence watchdog, `reconnect()`; `disconnect()` is final.
-- Refusals before anything is sent: a magic number the core cannot transmit, a volume the wire cannot carry, a
-  comment that would not read back.
-- Wheels: Linux x86-64 with the core and a .NET runtime bundled, and a pure wheel that carries the core.