pmt5api 1.0.0__tar.gz → 1.2.0__tar.gz

pmt5api-1.2.0/CHANGELOG.md

@@ -0,0 +1,133 @@
+# Changelog — pmt5api
+
+## [1.2.0] — 2026-11-06
+
+Bundles **wmt5api 3.2.1**. A minor release with a **Breaking** section, like the core's: history is always asked for
+by a window you choose.
+
+### Breaking — history is always asked for by window
+- **`history(start, end)` and `summary(start, end)` need both ends.** `history()` no longer defaults to the last 30
+  days and `summary()` no longer means "all time" (the core read every deal since 1970 for it, on every call). A
+  missing or reversed window raises `InvalidRequestError` before anything is sent; `request_history(start, end)`
+  likewise.
+- **One call covers at most `max_history_days` (366 by default).** A longer window raises `InvalidRequestError`
+  before anything is sent. Ask window by window and add the results up, or set `Client(max_history_days=...)` /
+  `c.max_history_days` when you mean one long download (`0` removes the limit; the ends stay required).
+  `equity_history(start)` and `calibrate_money_scale(start)` run to now, so their start is at most that long ago (an
+  older one makes `calibrate_money_scale` return `False`, the reason in `money_scale_evidence`).
+- What to change: `c.summary()` → `c.summary(start, end)`; `c.history()` → `c.history(start, end)` (for "up to now",
+  `end = c.server_time`); a calibration over two years → over at most one.
+
+### Added
+- `Client.max_history_days` (read and write) and the constructor argument of the same name.
+- `Client.server_name`: the name of the trade server the session logged in to (for example `ICMarketsSC-Demo`).
+
+### Changed (core wmt5api 3.2.0 / 3.2.1)
+- `history()` asks the server for your window only (the server answers in whole calendar months; before, three more
+  months were asked for on every call). A position closed in the window but held longer than three months before it
+  is now listed in `orders` (up to a year back); a position whose deals arrived in different pages is no longer
+  dropped.
+- Two `history()` calls at once on one client run one after the other instead of failing with `BusyError`.
+
+### Fixed (this package)
+- **The platform wheel could not start on a machine that also has a newer .NET installed on `PATH`** (for example a
+  system .NET 10 next to the bundled .NET 9): the loader under pythonnet asked that `dotnet` for its runtimes, took
+  the newest and looked for it in the bundled runtime — `RuntimeNotFoundError` ("needs the .NET 8 (or later)
+  runtime"), on 1.1.2 too. The runtime is now started at a version the chosen runtime folder holds, and the message
+  says which runtime it tried.
+
+### Fixed (core wmt5api 3.2.0 / 3.2.1)
+- **Events could reach callbacks out of order** — an order's close before its open, an older price after a newer one,
+  a disconnect before the connect. Quotes, order updates, order progress, connect progress and history chunks now
+  arrive in the order the client received them; a throwing handler no longer drops the rest of a batch.
+- **A market order or close with the default fill policy could use a filling mode the symbol does not accept**, and
+  the broker refused it (`UNSUPPORTED_FILLING_MODE`): the symbol's declared modes are a bit mask and were read as one
+  value. The default now picks a declared mode (fill-or-kill if declared, else immediate-or-cancel, else return on an
+  exchange).
+- `Order.fill_policy` of a market order filled immediate-or-cancel read fill-or-kill; it reports the mode the server
+  confirmed.
+- `equity_history()`: the documentation no longer says "empty" for a window with no deal (it is a flat line).
+
+### Security (core wmt5api 3.2.0)
+- `token_url` must be `https` (plain `http` only for a loopback host) and carry no user information, query or
+  fragment; redirects from the licence service are not followed (they would re-send the key).
+- A login already bound to another trading account under your licence is refused with `LicenseError` reason
+  `AccountLimitReached` and a message that says so.
+
+## [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
+- A `bars()` timeout says the budget of the call (`not complete within 0.5 s`), not what was left for the last block.
+- `Order` and `Deal` money fields (profit, swap, commission, fee) carry no binary noise (`1.3900000000000001` is `1.39`).
+- README: a connect to an unreachable licence service waits about twice `token_timeout`.
+
+## [1.1.1] — 2026-10-14
+
+From the Windows re-test of 1.1.0 (13 notes, one S2). Bundles wmt5api 3.1.2.
+
+### Fixed
+- **`equity_history()` returned `[]` for a window with no deal** (an idle account): the balance curve is now a flat line
+  at the current balance (core `wmt5api 3.1.2`). A script that read `eq[-1]` on an idle account raised `IndexError`.
+- Account money figures carry no binary noise (`1635341.7899999998` is `1635341.79`).
+- A bars timeout states a sub-second wait as it is (`0.5 s`, not `0 s`).
+- A missing .NET runtime on a **32-bit** Python says that 32-bit Python needs the 32-bit runtime.
+- `SymbolInfo` has a meaning for every field in the reference.
+- README: ticks and their `time`, that the server enforces volume min/step, the minute rounding of an expiry, 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
+wmt5api 3.1.1. 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 wmt5api 3.1.1 — **`Deal.price` / `Deal.open_price` were swapped on a closing deal**, a pending sell order reported `DealBuy`, and `history()` omitted cancelled and expired pending orders.
+
+### 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.
+- `LoginRejectedError` (a `ServerError`): the broker refused the login — `connect()` raises it for a wrong account or password instead of a bare `ServerError`; a dial that times out is a `ConnectError`, as on MT4.
+
+## [1.0.0] — 2026-10-12
+
+First release. `pmt5api` exposes every public capability of the wmt5api 3.x C# library to Python.
+
+### Capabilities
+- Connection and session: licensing, failover, `auto_reconnect`, proxies (SOCKS4/SOCKS5/HTTPS), client certificate,
+  all timeouts, connect-progress events, server time and account mode.
+- Market data: symbols with trading rules and sessions, commissions, quotes and subscriptions (callbacks, iterators,
+  asyncio), bars M1–D1 with tick volume, tick value and contract size.
+- Account: balances and margins (with and without swap/commission), orders, positions, closed orders, history and
+  deal history (blocking and event-driven), realized summary, balance/equity curve.
+- Sizing and risk: money-scale calibration, lots-for-risk with evidence, required margin, order profit.
+- Order entry: market, pending (limit, stop, stop-limit), expiration, fill policy, modify, partial close, close-by,
+  cancel — synchronous, with request ids and progress events, and awaitable; magic number on orders and deals.
+- Offline helpers and administration: `servers.dat` read and write, demo account request, password change.
+- Diagnostics: the core's log into Python `logging`.
+- Parity manifest `pmt5api.COVERAGE`, checked against the DLL by the test suite; generated API reference and a
+  C#-to-Python table.
+
+### Packaging
+- Linux x86-64 wheel carrying the core and the .NET 9 runtime (`manylinux_2_28`); a pure wheel carrying the core;
+  an sdist.
+
+### Verified
+Against real demo accounts, from clean containers without .NET (Python 3.9, 3.12, 3.13; glibc 2.28 and 2.41):
+read-only and trading suites, reconnects (drops, a refused window, a silent link), every shipped example, and a
+three-hour unattended run (4 recovered drops, no errors, memory flat after warm-up).
+Not verified: Windows, macOS, arm64, musl; netting accounts; client certificates.

{pmt5api-1.0.0 → pmt5api-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pmt5api
-Version: 1.0.0
+Version: 1.2.0
 Summary: Complete Python interface to the wmt5api MetaTrader 5 client library (market data, account, sizing, order entry, events).
 Project-URL: Homepage, https://mtapi.one
 Author: Sen Trading
@@ -37,19 +37,25 @@ No MetaTrader terminal is needed — the core talks to your broker directly.
 
 **Parity with the C# library is measured, not claimed:** `pmt5api.COVERAGE` maps every public member of the C#
 `MT5API` class 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/pmt5api/docs/FROM-CSHARP.md) is that table;
-[`docs/API.md`](src/pmt5api/docs/API.md) is the reference.
+member that is not accounted for. `pmt5api/docs/FROM-CSHARP.md` (inside the installed package) is that table;
+`pmt5api/docs/API.md` (inside the installed package; `python -m pmt5api` 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 pmt5api-<version>-py3-none-manylinux_2_28_x86_64.whl
+pip install pmt5api
 ```
 
-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 pmt5api-<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 pmt5api`. Check it with `python -m pmt5api`: it prints
+the versions, finds the runtime and constructs a client offline. Set the key in the shell that runs your program —
+PowerShell: `$env:WMTAPI_KEY = "wk_..."`, cmd: `set WMTAPI_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`.
 
 You also need your **API key** (`wk_…`, the same key you use with wmt5api):
 
@@ -101,6 +107,16 @@ bars; higher timeframes are built from them, aligned to the server's calendar (a
 bar at 00, 04, 08, … server time, a week on Sunday, a month on the 1st), with `tick_volume` summed. Minutes after
 `end` are not used; the last bar may still be forming. `spread` is present on M1 bars only.
 
+**What a request costs.** The server hands the one-minute bars over in blocks of about two weeks, so the time of a
+`bars()` call grows with how far back it reaches, not with the timeframe. Measured from a datacentre against a
+broker's demo server: 5 000 one-minute bars 0.4 s; 100 `D1` bars 3 s; 5 000 `H1` bars 9 s; 500 `D1` bars 16 s;
+1 000 `D1` bars 32 s (your link and your broker will differ). The default budget is `bars_timeout` plus a second per
+block the request needs, so these finish without a `timeout=`; pass one to bound the call yourself.
+
+**MT4 and MT5 differ here.** On MT5 `end=` includes the bar stamped exactly `end` and the bar that is still forming; the
+MT4 package returns completed bars only and excludes a bar that opens at `end`. Code that runs on both has to drop
+the forming MT5 bar itself.
+
 ### Live quotes
 
 ```python
@@ -123,19 +139,25 @@ c.subscribe("EURUSD")
 remove()
 ```
 
-Callbacks are delivered by **one dispatcher thread per client**, one at a time, in arrival order — you need no locks
+Callbacks are delivered by **one dispatcher thread per client**, one at a time, in the order the events arrived — you need no locks
 between callbacks, and a slow callback does not stall the connection. If a callback falls more than 20,000 events
 behind, the oldest events are dropped, a warning is logged and `c.events_dropped` counts them. An exception raised
 inside a callback is logged (`logging.getLogger("pmt5api")`) and swallowed. Order updates keep the state they had at
 the moment they arrived (they are snapshots). The iterators attach when you create them, drop the oldest item when the
 consumer falls behind, and detach on `close()` / `async with` / garbage collection.
 
+A tick's `time` is the server's: on some brokers about one tick in a hundred carries a time slightly earlier than the
+previous tick of the same symbol (the feed is merged from several sources). Delivery order is arrival order; sort by
+`time` if you need the market's order.
+
 ## Trading
 
 ```python
+from datetime import datetime
+
 o = c.buy("EURUSD", 0.10, sl=1.0950, tp=1.1100, magic=424242)   # 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("EURUSD", "buy_stop_limit", 0.10, 1.1200, stop_limit=1.1190,
                   expiration=datetime(2026, 12, 31, 23, 0))   # also buy_limit sell_limit buy_stop sell_stop
@@ -159,6 +181,12 @@ rid = c.buy_async("EURUSD", 0.10)
 `aclose`, `acancel`, `aquote`. Cancelling the `await` (a `wait_for` timeout, a cancelled task) does not recall a request
 that is already on its way: the order may still be sent, so check `orders()` afterwards.
 
+**The server, not the library, enforces volume rules.** A volume below the minimum or off the step is sent and refused
+(`ServerError` `INVALID_VOLUME`); `symbol(name)` has `min_lots`, `max_lots` and `lots_step` to check against first. A
+pending order's expiration is stored to the minute (rounded **down**), so an order can expire up to a minute before the
+time you asked for. Pressing Ctrl+C while `connect()` is dialling is honoured when the dial ends (up to
+`connect_timeout`), not at once.
+
 **Test on a demo account first.** Nothing here is ever retried or resent for you: if the server does not confirm in
 time the call raises `RequestTimeout` and the order **may have been accepted** — look at `orders()` before sending
 again. `NoQuoteError` is different: no price was available, so nothing was sent. `orders()` can lag a moment behind
@@ -174,8 +202,10 @@ Do not size a trade from a one-line formula: what a price unit is worth depends
 from your own closed deals and refuses to size without that evidence:
 
 ```python
-if c.calibrate_money_scale(datetime(2025, 1, 1)):                 # read-only; places no order
-    r = c.lots_for_risk("EURUSD", entry_price=1.1000, stop_price=1.0950, risk_amount=50.0)
+from datetime import timedelta
+
+if c.calibrate_money_scale(c.server_time - timedelta(days=365)):  # read-only; places no order; at most a year back
+    r = c.lots_for_risk("EURUSD", entry_price=1.1000, stop_price=1.0950, risk_amount=50.0, side="buy")
     for w in r.warnings:
         print("warning:", w)              # read these: ok can still be True with a caveat
     if r.ok and r.expected_loss_at_stop <= 50.0 * 1.05:
@@ -198,12 +228,29 @@ to be checked. Also: `required_margin(symbol, lots)`, `order_profit(symbol, open
 | `account(refresh=True)` | `AccountInfo` — balance, equity, floating P/L (with and without swap/commission), margin, free margin, margin level, leverage, account mode, contact details |
 | `orders()` / `positions()` / `closed_orders()` | `list[Order]` — working / open positions only / what this session saw close |
 | `history(start, end)` / `deal_history(year, month)` | `History` — `.orders` and `.deals` (the ledger, including deposits and withdrawals) |
-| `summary(start=None, end=None)` | `AccountSummary` — realized profit, deposits, withdrawals, from the deal ledger |
+| `summary(start, end)` | `AccountSummary` — realized profit, deposits, withdrawals, from the deal ledger |
 | `equity_history(start, "D1")` | `list[EquityPoint]` — balance (exact) and equity (reconstructed) curve with drawdowns |
 | `request_history(...)`, `request_bars(...)` | without waiting; the data arrives through `on_history` / `on_quote_history` |
 
 Times are naive `datetime` values in the **broker's server time**, as the server reports them; an unset time is `None`.
 
+**History is asked for by window.** `history()` and `summary()` take a start and an end, and one call covers at most
+`max_history_days` (366 by default; set it on the client, `0` removes the limit); `equity_history()` and
+`calibrate_money_scale()` run from their start to now, so the start is at most that long ago. A missing, reversed or longer window raises
+`InvalidRequestError` before anything is sent. For a longer period, ask window by window and add the results up:
+
+```python
+from datetime import timedelta
+
+end = c.server_time                                   # server time; "up to now"
+h = c.history(end - timedelta(days=30), end)             # .orders and .deals
+year = c.summary(end - timedelta(days=365), end)
+```
+
+The server answers history in whole calendar months; `history()` keeps your window, and lists a position closed in it
+whose opening deal is earlier (up to a year before the window). A window with no deal in it gives a flat equity curve
+at the balance, never an empty one.
+
 `account()` first quotes each open position's symbol once and recalculates profits, so equity, profit and margin
 level are current (a cold read would otherwise show equity equal to balance). Pass `refresh=False` to skip that.
 
@@ -211,7 +258,9 @@ level are current (a cold read would otherwise show equity equal to balance). Pa
 
 `on_quote`, `on_order_update`, `on_order_progress`, `on_connect_progress`, `on_history`, `on_quote_history`,
 `on_symbols_update`, `on_symbol_update` — each returns a function that removes the callback. `quotes()` and
-`order_updates()` (and the `a…` async versions) turn a stream into an iterator.
+`order_updates()` (and the `a…` async versions) turn a stream into an iterator. Events reach you in the order the
+client received them — an order's open before its close, ticks in time order — and callbacks run one at a time on the
+client's own thread.
 
 ## Staying connected
 
@@ -228,16 +277,24 @@ subscriptions are restored, cached snapshots are not.
 | API key | `api_key=` | `WMTAPI_KEY` |
 | Licence service URL (leave at its default) | `token_url=` | `WMTAPI_TOKEN_URL` |
 | Core library (only if you do not use a wheel that carries it) | `dll_path=` | `WMTAPI_DLL` |
-| Timeouts (seconds, each > 0) | `connect_timeout` (one attempt on one server), `cluster_member_timeout` (per server while failing over), `token_timeout`, `execution_timeout`, `quote_timeout` / `history_timeout` / `bars_timeout` (the defaults of `quote`, `history`, `bars`), `ping_interval`, `no_message_timeout` | — |
-| Reconnect | `auto_reconnect`, `reconnect_backoff`, `reconnect_max_backoff`, `reconnect_max_attempts` | — |
+| Timeouts (seconds, each > 0) | `connect_timeout` (the whole connect; default 30), `cluster_member_timeout` (per server while failing over; 10), `token_timeout` (10), `execution_timeout` (a trade confirmation; 30), `quote_timeout` (10) / `history_timeout` (30) / `bars_timeout` (10, plus a second per two weeks of one-minute bars a `bars()` call needs) — the defaults of `quote`, `history`, `bars`, `ping_interval` (20), `no_message_timeout` (30) | — |
+| Reconnect | `auto_reconnect`, `reconnect_backoff` (3, doubling up to `reconnect_max_backoff`, 30), `reconnect_max_attempts` (0 = no limit) | — |
 | Proxy | `proxy=Proxy("socks5" \| "socks4" \| "https", host, port, user, password)` — `host` must be an IP address | — |
 | Client certificate / common key | `certificate=`, `certificate_password=`, `common_key=` | — |
+| History window | `max_history_days=` (366; `0` = no limit) — also a client attribute | — |
 | .NET runtime location | — | `DOTNET_ROOT` |
 
 A core path you give (argument or `WMTAPI_DLL`) is used exactly as given and is an error if it does not exist. The
 .NET runtime is taken from `DOTNET_ROOT` if you set it, else the runtime bundled in the wheel, else an installed one.
 The bundled runtime runs in invariant-culture mode on machines without ICU.
 
+**These two settings decide what code runs in your process.** `WMTAPI_DLL` (or `dll_path=`) names the library that is
+loaded, and `DOTNET_ROOT` (or, without it, the `dotnet` found on `PATH`) names the .NET runtime that is started;
+both run with your rights. Set them only from configuration you control, and do not run with an environment
+someone else can change. With `enable_core_logging()` switched on, the package logs once when either was chosen
+by the environment. The licence service URL must be `https` (plain `http` only for a loopback test service), and
+redirects from it are not followed.
+
 ### Diagnostics
 
 ```python
@@ -252,6 +309,10 @@ pmt5api.enable_core_logging()          # the core's own messages -> logging.getL
 `request_demo_account(DemoAccountRequest(...), host, port)` asks a broker for a demo account (it creates a real
 account at that broker: use it deliberately); `c.change_password(new, investor=False)`.
 
+`python -m pmt5api` prints what is installed and whether it works here (`--connect` also reads an account, using
+`PMT5_LOGIN`, `PMT5_PASSWORD`, `PMT5_HOST` — a bare host, or `host:port`, or the port in `PMT5_PORT` — and the key in
+`WMTAPI_KEY`); the output holds no secrets and is what to send when asking for help.
+
 ## Errors
 
 Everything the core raises reaches you as one of these, all subclasses of `pmt5api.WmtError`; the original
@@ -260,7 +321,7 @@ exception stays available as `__cause__`.
 | Exception | Meaning |
 |---|---|
 | `LicenseError` | The licence service refused the key. `.reason` is one of `NoKey`, `Invalid`, `Expired`, `Revoked`, `RateLimited`, `LoginNotAllowed`, `AccountLimitReached`, `Unknown`. |
-| `TokenServiceError` | The licence service could not be reached or answered unusably — retry, don't re-prompt for a key. |
+| `TokenServiceError` | The licence service could not be reached or answered unusably — retry, don't re-prompt for a key. (`token_timeout` bounds one request and a failed request is tried again once, so a connect to an unreachable licence service can wait about twice that.) |
 | `ConnectError` | The broker's access server (or the network, or a proxy) could not be reached. |
 | `ConnectionLostError` | An established connection dropped (the core's `Disconnected`). |
 | `ServerError` / `InvestorModeError` | The broker refused the request (wrong login or password, a rejected order / a read-only login tried to trade). `.code` is the server's return code by name (`REQUOTE`, `NO_MONEY`, `INVALID_PRICE`, …). |
@@ -304,6 +365,10 @@ moved by 4 MB), threads and file descriptors stayed flat. Every shipped example
 
 ## Known limitations
 
+- **Sizing needs evidence from the account's own closed deals.** On an account whose deals all carry swap or
+  commission, or whose deals do not have the shape the calibration can read (a Tickmill demo, for one), `calibrate_money_scale`
+  finds no symbol to measure from and `lots_for_risk` refuses: that is the intended answer, not an error. `tick_value()`
+  and `required_margin()` still work, and the refusal says what was missing.
 - **Linux x86-64 is the verified platform.** Windows, macOS, arm64 and musl-based Linux have not been verified.
 - Netting accounts have not been verified (the available demo accounts are all hedging).
 - Client certificates (`certificate=`), `common_key=` and `request_demo_account` have been unit-tested but not run

{pmt5api-1.0.0 → pmt5api-1.2.0}/README.md

@@ -10,19 +10,25 @@ No MetaTrader terminal is needed — the core talks to your broker directly.
 
 **Parity with the C# library is measured, not claimed:** `pmt5api.COVERAGE` maps every public member of the C#
 `MT5API` class 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/pmt5api/docs/FROM-CSHARP.md) is that table;
-[`docs/API.md`](src/pmt5api/docs/API.md) is the reference.
+member that is not accounted for. `pmt5api/docs/FROM-CSHARP.md` (inside the installed package) is that table;
+`pmt5api/docs/API.md` (inside the installed package; `python -m pmt5api` 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 pmt5api-<version>-py3-none-manylinux_2_28_x86_64.whl
+pip install pmt5api
 ```
 
-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 pmt5api-<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 pmt5api`. Check it with `python -m pmt5api`: it prints
+the versions, finds the runtime and constructs a client offline. Set the key in the shell that runs your program —
+PowerShell: `$env:WMTAPI_KEY = "wk_..."`, cmd: `set WMTAPI_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`.
 
 You also need your **API key** (`wk_…`, the same key you use with wmt5api):
 
@@ -74,6 +80,16 @@ bars; higher timeframes are built from them, aligned to the server's calendar (a
 bar at 00, 04, 08, … server time, a week on Sunday, a month on the 1st), with `tick_volume` summed. Minutes after
 `end` are not used; the last bar may still be forming. `spread` is present on M1 bars only.
 
+**What a request costs.** The server hands the one-minute bars over in blocks of about two weeks, so the time of a
+`bars()` call grows with how far back it reaches, not with the timeframe. Measured from a datacentre against a
+broker's demo server: 5 000 one-minute bars 0.4 s; 100 `D1` bars 3 s; 5 000 `H1` bars 9 s; 500 `D1` bars 16 s;
+1 000 `D1` bars 32 s (your link and your broker will differ). The default budget is `bars_timeout` plus a second per
+block the request needs, so these finish without a `timeout=`; pass one to bound the call yourself.
+
+**MT4 and MT5 differ here.** On MT5 `end=` includes the bar stamped exactly `end` and the bar that is still forming; the
+MT4 package returns completed bars only and excludes a bar that opens at `end`. Code that runs on both has to drop
+the forming MT5 bar itself.
+
 ### Live quotes
 
 ```python
@@ -96,19 +112,25 @@ c.subscribe("EURUSD")
 remove()
 ```
 
-Callbacks are delivered by **one dispatcher thread per client**, one at a time, in arrival order — you need no locks
+Callbacks are delivered by **one dispatcher thread per client**, one at a time, in the order the events arrived — you need no locks
 between callbacks, and a slow callback does not stall the connection. If a callback falls more than 20,000 events
 behind, the oldest events are dropped, a warning is logged and `c.events_dropped` counts them. An exception raised
 inside a callback is logged (`logging.getLogger("pmt5api")`) and swallowed. Order updates keep the state they had at
 the moment they arrived (they are snapshots). The iterators attach when you create them, drop the oldest item when the
 consumer falls behind, and detach on `close()` / `async with` / garbage collection.
 
+A tick's `time` is the server's: on some brokers about one tick in a hundred carries a time slightly earlier than the
+previous tick of the same symbol (the feed is merged from several sources). Delivery order is arrival order; sort by
+`time` if you need the market's order.
+
 ## Trading
 
 ```python
+from datetime import datetime
+
 o = c.buy("EURUSD", 0.10, sl=1.0950, tp=1.1100, magic=424242)   # 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("EURUSD", "buy_stop_limit", 0.10, 1.1200, stop_limit=1.1190,
                   expiration=datetime(2026, 12, 31, 23, 0))   # also buy_limit sell_limit buy_stop sell_stop
@@ -132,6 +154,12 @@ rid = c.buy_async("EURUSD", 0.10)
 `aclose`, `acancel`, `aquote`. Cancelling the `await` (a `wait_for` timeout, a cancelled task) does not recall a request
 that is already on its way: the order may still be sent, so check `orders()` afterwards.
 
+**The server, not the library, enforces volume rules.** A volume below the minimum or off the step is sent and refused
+(`ServerError` `INVALID_VOLUME`); `symbol(name)` has `min_lots`, `max_lots` and `lots_step` to check against first. A
+pending order's expiration is stored to the minute (rounded **down**), so an order can expire up to a minute before the
+time you asked for. Pressing Ctrl+C while `connect()` is dialling is honoured when the dial ends (up to
+`connect_timeout`), not at once.
+
 **Test on a demo account first.** Nothing here is ever retried or resent for you: if the server does not confirm in
 time the call raises `RequestTimeout` and the order **may have been accepted** — look at `orders()` before sending
 again. `NoQuoteError` is different: no price was available, so nothing was sent. `orders()` can lag a moment behind
@@ -147,8 +175,10 @@ Do not size a trade from a one-line formula: what a price unit is worth depends
 from your own closed deals and refuses to size without that evidence:
 
 ```python
-if c.calibrate_money_scale(datetime(2025, 1, 1)):                 # read-only; places no order
-    r = c.lots_for_risk("EURUSD", entry_price=1.1000, stop_price=1.0950, risk_amount=50.0)
+from datetime import timedelta
+
+if c.calibrate_money_scale(c.server_time - timedelta(days=365)):  # read-only; places no order; at most a year back
+    r = c.lots_for_risk("EURUSD", entry_price=1.1000, stop_price=1.0950, risk_amount=50.0, side="buy")
     for w in r.warnings:
         print("warning:", w)              # read these: ok can still be True with a caveat
     if r.ok and r.expected_loss_at_stop <= 50.0 * 1.05:
@@ -171,12 +201,29 @@ to be checked. Also: `required_margin(symbol, lots)`, `order_profit(symbol, open
 | `account(refresh=True)` | `AccountInfo` — balance, equity, floating P/L (with and without swap/commission), margin, free margin, margin level, leverage, account mode, contact details |
 | `orders()` / `positions()` / `closed_orders()` | `list[Order]` — working / open positions only / what this session saw close |
 | `history(start, end)` / `deal_history(year, month)` | `History` — `.orders` and `.deals` (the ledger, including deposits and withdrawals) |
-| `summary(start=None, end=None)` | `AccountSummary` — realized profit, deposits, withdrawals, from the deal ledger |
+| `summary(start, end)` | `AccountSummary` — realized profit, deposits, withdrawals, from the deal ledger |
 | `equity_history(start, "D1")` | `list[EquityPoint]` — balance (exact) and equity (reconstructed) curve with drawdowns |
 | `request_history(...)`, `request_bars(...)` | without waiting; the data arrives through `on_history` / `on_quote_history` |
 
 Times are naive `datetime` values in the **broker's server time**, as the server reports them; an unset time is `None`.
 
+**History is asked for by window.** `history()` and `summary()` take a start and an end, and one call covers at most
+`max_history_days` (366 by default; set it on the client, `0` removes the limit); `equity_history()` and
+`calibrate_money_scale()` run from their start to now, so the start is at most that long ago. A missing, reversed or longer window raises
+`InvalidRequestError` before anything is sent. For a longer period, ask window by window and add the results up:
+
+```python
+from datetime import timedelta
+
+end = c.server_time                                   # server time; "up to now"
+h = c.history(end - timedelta(days=30), end)             # .orders and .deals
+year = c.summary(end - timedelta(days=365), end)
+```
+
+The server answers history in whole calendar months; `history()` keeps your window, and lists a position closed in it
+whose opening deal is earlier (up to a year before the window). A window with no deal in it gives a flat equity curve
+at the balance, never an empty one.
+
 `account()` first quotes each open position's symbol once and recalculates profits, so equity, profit and margin
 level are current (a cold read would otherwise show equity equal to balance). Pass `refresh=False` to skip that.
 
@@ -184,7 +231,9 @@ level are current (a cold read would otherwise show equity equal to balance). Pa
 
 `on_quote`, `on_order_update`, `on_order_progress`, `on_connect_progress`, `on_history`, `on_quote_history`,
 `on_symbols_update`, `on_symbol_update` — each returns a function that removes the callback. `quotes()` and
-`order_updates()` (and the `a…` async versions) turn a stream into an iterator.
+`order_updates()` (and the `a…` async versions) turn a stream into an iterator. Events reach you in the order the
+client received them — an order's open before its close, ticks in time order — and callbacks run one at a time on the
+client's own thread.
 
 ## Staying connected
 
@@ -201,16 +250,24 @@ subscriptions are restored, cached snapshots are not.
 | API key | `api_key=` | `WMTAPI_KEY` |
 | Licence service URL (leave at its default) | `token_url=` | `WMTAPI_TOKEN_URL` |
 | Core library (only if you do not use a wheel that carries it) | `dll_path=` | `WMTAPI_DLL` |
-| Timeouts (seconds, each > 0) | `connect_timeout` (one attempt on one server), `cluster_member_timeout` (per server while failing over), `token_timeout`, `execution_timeout`, `quote_timeout` / `history_timeout` / `bars_timeout` (the defaults of `quote`, `history`, `bars`), `ping_interval`, `no_message_timeout` | — |
-| Reconnect | `auto_reconnect`, `reconnect_backoff`, `reconnect_max_backoff`, `reconnect_max_attempts` | — |
+| Timeouts (seconds, each > 0) | `connect_timeout` (the whole connect; default 30), `cluster_member_timeout` (per server while failing over; 10), `token_timeout` (10), `execution_timeout` (a trade confirmation; 30), `quote_timeout` (10) / `history_timeout` (30) / `bars_timeout` (10, plus a second per two weeks of one-minute bars a `bars()` call needs) — the defaults of `quote`, `history`, `bars`, `ping_interval` (20), `no_message_timeout` (30) | — |
+| Reconnect | `auto_reconnect`, `reconnect_backoff` (3, doubling up to `reconnect_max_backoff`, 30), `reconnect_max_attempts` (0 = no limit) | — |
 | Proxy | `proxy=Proxy("socks5" \| "socks4" \| "https", host, port, user, password)` — `host` must be an IP address | — |
 | Client certificate / common key | `certificate=`, `certificate_password=`, `common_key=` | — |
+| History window | `max_history_days=` (366; `0` = no limit) — also a client attribute | — |
 | .NET runtime location | — | `DOTNET_ROOT` |
 
 A core path you give (argument or `WMTAPI_DLL`) is used exactly as given and is an error if it does not exist. The
 .NET runtime is taken from `DOTNET_ROOT` if you set it, else the runtime bundled in the wheel, else an installed one.
 The bundled runtime runs in invariant-culture mode on machines without ICU.
 
+**These two settings decide what code runs in your process.** `WMTAPI_DLL` (or `dll_path=`) names the library that is
+loaded, and `DOTNET_ROOT` (or, without it, the `dotnet` found on `PATH`) names the .NET runtime that is started;
+both run with your rights. Set them only from configuration you control, and do not run with an environment
+someone else can change. With `enable_core_logging()` switched on, the package logs once when either was chosen
+by the environment. The licence service URL must be `https` (plain `http` only for a loopback test service), and
+redirects from it are not followed.
+
 ### Diagnostics
 
 ```python
@@ -225,6 +282,10 @@ pmt5api.enable_core_logging()          # the core's own messages -> logging.getL
 `request_demo_account(DemoAccountRequest(...), host, port)` asks a broker for a demo account (it creates a real
 account at that broker: use it deliberately); `c.change_password(new, investor=False)`.
 
+`python -m pmt5api` prints what is installed and whether it works here (`--connect` also reads an account, using
+`PMT5_LOGIN`, `PMT5_PASSWORD`, `PMT5_HOST` — a bare host, or `host:port`, or the port in `PMT5_PORT` — and the key in
+`WMTAPI_KEY`); the output holds no secrets and is what to send when asking for help.
+
 ## Errors
 
 Everything the core raises reaches you as one of these, all subclasses of `pmt5api.WmtError`; the original
@@ -233,7 +294,7 @@ exception stays available as `__cause__`.
 | Exception | Meaning |
 |---|---|
 | `LicenseError` | The licence service refused the key. `.reason` is one of `NoKey`, `Invalid`, `Expired`, `Revoked`, `RateLimited`, `LoginNotAllowed`, `AccountLimitReached`, `Unknown`. |
-| `TokenServiceError` | The licence service could not be reached or answered unusably — retry, don't re-prompt for a key. |
+| `TokenServiceError` | The licence service could not be reached or answered unusably — retry, don't re-prompt for a key. (`token_timeout` bounds one request and a failed request is tried again once, so a connect to an unreachable licence service can wait about twice that.) |
 | `ConnectError` | The broker's access server (or the network, or a proxy) could not be reached. |
 | `ConnectionLostError` | An established connection dropped (the core's `Disconnected`). |
 | `ServerError` / `InvestorModeError` | The broker refused the request (wrong login or password, a rejected order / a read-only login tried to trade). `.code` is the server's return code by name (`REQUOTE`, `NO_MONEY`, `INVALID_PRICE`, …). |
@@ -277,6 +338,10 @@ moved by 4 MB), threads and file descriptors stayed flat. Every shipped example
 
 ## Known limitations
 
+- **Sizing needs evidence from the account's own closed deals.** On an account whose deals all carry swap or
+  commission, or whose deals do not have the shape the calibration can read (a Tickmill demo, for one), `calibrate_money_scale`
+  finds no symbol to measure from and `lots_for_risk` refuses: that is the intended answer, not an error. `tick_value()`
+  and `required_margin()` still work, and the refusal says what was missing.
 - **Linux x86-64 is the verified platform.** Windows, macOS, arm64 and musl-based Linux have not been verified.
 - Netting accounts have not been verified (the available demo accounts are all hedging).
 - Client certificates (`certificate=`), `common_key=` and `request_demo_account` have been unit-tested but not run

{pmt5api-1.0.0 → pmt5api-1.2.0}/examples/pnl.py

@@ -3,7 +3,7 @@
     PMT5_LOGIN=... PMT5_PASSWORD=... PMT5_HOST=... python pnl.py
 """
 import os
-from datetime import datetime, timedelta
+from datetime import timedelta
 
 from pmt5api import Client
 
@@ -13,10 +13,12 @@ with Client(int(os.environ["PMT5_LOGIN"]), os.environ["PMT5_PASSWORD"], os.envir
     print("balance %.2f  equity %.2f  floating %.2f  (swap %.2f, commission %.2f)"
           % (a.balance, a.equity, a.floating_pl, a.swap, a.commission))
 
-    s = c.summary()                                   # from the deal ledger; blocks while it downloads
-    print("realized %.2f  deposits %.2f  withdrawals %.2f" % (s.realized_profit, s.deposit, s.withdrawal))
+    now = c.server_time                               # history windows are in the broker's server time
+    s = c.summary(now - timedelta(days=365), now)     # the last year (at most max_history_days per call); blocks
+    print("last 365 days: realized %.2f  deposits %.2f  withdrawals %.2f"
+          % (s.realized_profit, s.deposit, s.withdrawal))
 
-    curve = c.equity_history(datetime.now() - timedelta(days=30), "D1")
+    curve = c.equity_history(now - timedelta(days=30), "D1")
     for p in curve[-5:]:
         flag = "  (incomplete)" if p.incomplete else ""
         print("%s  balance %.2f  equity %.2f  drawdown %.2f%%%s"

{pmt5api-1.0.0 → pmt5api-1.2.0}/examples/sizing.py

@@ -4,7 +4,7 @@
 """
 import os
 import sys
-from datetime import datetime, timedelta
+from datetime import timedelta
 
 from pmt5api import Client
 
@@ -19,8 +19,8 @@ with Client(int(os.environ["PMT5_LOGIN"]), os.environ["PMT5_PASSWORD"], os.envir
     acct = c.account()
     print("account currency %s, equity %.2f" % (acct.currency, acct.equity))
 
-    # 1. measure the account's own conventions from its closed deals (read-only; places no order)
-    if not c.calibrate_money_scale(datetime.now() - timedelta(days=730)):
+    # 1. measure the account's own conventions from its closed deals of the last year (read-only; places no order)
+    if not c.calibrate_money_scale(c.server_time - timedelta(days=365)):
         sys.exit("cannot size yet: " + c.money_scale_evidence)
     print("money scale %s" % c.money_scale)
 

{pmt5api-1.0.0 → pmt5api-1.2.0}/src/pmt5api/__init__.py

@@ -8,7 +8,7 @@ from ._coverage import COVERAGE, TYPES
 from .bars import Bar, QuoteHistoryEvent, TIMEFRAMES, aggregate
 from .client import Client, Proxy
 from .diagnostics import enable_core_logging
-from .errors import (BusyError, ConnectError, NoQuoteError, ConnectionLostError, CoreNotFoundError, InvalidRequestError, InvestorModeError,
+from .errors import (BusyError, ConnectError, NoQuoteError, ConnectionLostError, CoreNotFoundError, InvalidRequestError, InvestorModeError, LoginRejectedError,
                      LicenseError, NotConnectedError, ProxyError, RequestTimeout, RuntimeNotFoundError,
                      ServerError, TokenServiceError, WmtError)
 from .frames import to_frame
@@ -17,7 +17,7 @@ from .models import (AccountInfo, AccountSummary, BaseInfo, CommissionInfo, Comm
                      OrderUpdate, Quote, ServerRecord, SymbolInfo, SymbolSessions, TradingSession)
 from .servers import load_servers_dat, request_demo_account, save_servers_dat, tick_value_from_deal
 
-__version__ = "1.0.0"
+__version__ = "1.2.0"
 
 __all__ = [
     "Client", "Proxy",
@@ -28,7 +28,7 @@ __all__ = [
     "Bar", "TIMEFRAMES", "aggregate", "to_frame",
     "load_servers_dat", "save_servers_dat", "request_demo_account", "tick_value_from_deal", "enable_core_logging",
     "WmtError", "LicenseError", "TokenServiceError", "ConnectError", "ConnectionLostError", "NotConnectedError",
-    "ServerError", "InvestorModeError", "ProxyError", "RequestTimeout", "NoQuoteError", "InvalidRequestError", "BusyError",
+    "ServerError", "LoginRejectedError", "InvestorModeError", "ProxyError", "RequestTimeout", "NoQuoteError", "InvalidRequestError", "BusyError",
     "CoreNotFoundError",
     "RuntimeNotFoundError", "COVERAGE", "TYPES", "__version__",
 ]