pmt4api 1.0.0__tar.gz → 1.2.0__tar.gz

pmt4api-1.2.0/CHANGELOG.md

@@ -0,0 +1,102 @@
+# Changelog — pmt4api
+
+## [1.2.0] — 2026-11-06
+
+Bundles **wmt4api 3.4.0**. 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 downloaded every order since 1970 for it, on every call).
+  A missing or reversed window raises `InvalidRequestError` before anything is sent. `ahistory` likewise.
+- **One call covers at most `max_history_days` (366 by default).** A longer window raises `InvalidRequestError`
+  before a connection is opened or a licence request spent. 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)` runs to now, so its start is at most that long ago.
+- What to change: `c.summary()` → `c.summary(start, end)`; `c.history()` → `c.history(start, end)` (for "up to now",
+  `end = c.server_time`).
+
+### Added
+- `Client.max_history_days` (read and write) and the constructor argument of the same name.
+
+### 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 wmt4api 3.4.0)
+- **Order updates could reach `on_order_update` / `order_updates()` out of order** — a close before its open included
+  (seen on IC Markets: a commission modify before the open). They now arrive in the order the server sent them; the
+  same holds for quotes, order progress and connect / disconnect.
+- **`equity_history()` returned an empty list for a window with no closed order.** It is a flat line at the balance
+  (plus the floating P/L of open positions), the last point the live balance and equity — as in `pmt5api`.
+
+### Security (core wmt4api 3.4.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
+- `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.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pmt4api
-Version: 1.0.0
+Version: 1.2.0
 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:
@@ -215,22 +235,38 @@ cent-account scaling, so check the first result against your terminal. Also: `re
 | `balance`, `equity`, `margin`, `free_margin`, `margin_level`, `profit` | the same figures as cheap reads from the cache (no refresh; the margin may still wait for a conversion pair's first tick) |
 | `orders()` / `positions()` / `pending_orders()` / `order(ticket)` | `list[Order]` working / open positions / pending / one |
 | `history(start, end)` | `list[Order]` — closed orders and balance / credit entries, by close time |
-| `summary(start=None, end=None)` | `AccountSummary` — realized profit, deposits, withdrawals |
+| `summary(start, end)` | `AccountSummary` — realized profit, deposits, withdrawals |
 | `equity_history(start, "D1")` | `list[EquityPoint]` — balance (exact) and equity (reconstructed) curve with drawdowns |
 
 MT4 keeps one record for open positions, pending orders, closed orders and ledger entries: `Order.order_type` tells
 them apart (`Buy` / `Sell`, `BuyLimit` … , `Balance` / `Credit`), and `is_market`, `is_pending`, `is_capital_flow`
 say it directly. Times are naive `datetime` values in the **broker's server time**; 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()` runs from its
+start to now, so its 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"
+closed = c.history(end - timedelta(days=30), end)
+year = c.summary(end - timedelta(days=365), end)
+```
+
 `history()`, `summary()` and `equity_history()` each open their own short-lived broker connection and cost one
 licence request, which the licence service rate-limits per minute: fetch once and reuse the result. `history()`
-takes a `threading.Event` as `cancel=` to abandon the wait.
+takes a `threading.Event` as `cancel=` to abandon the wait. A window with no closed order in it gives a flat equity
+curve at the balance, never an empty one.
 
 ## Events
 
 `on_quote`, `on_order_update`, `on_order_progress`, `on_connect`, `on_disconnect`, `on_quote_history`,
 `on_symbols_update` — each returns a function that removes the callback. `quotes()`, `order_updates()` and
-`order_progress()` (and the `a…` async versions) turn a stream into an iterator.
+`order_progress()` (and the `a…` async versions) turn a stream into an iterator. Events reach you in the order the
+server sent them — a ticket's open before its modifications and its close — and callbacks run one at a time on the
+client's own thread.
 
 ## Staying connected
 
@@ -251,15 +287,23 @@ 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`) | — |
+| 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 `WMT4API_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. The MT4 core has no proxy support.
 
+**These two settings decide what code runs in your process.** `WMT4API_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
@@ -272,7 +316,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.2.0}/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:
@@ -188,22 +208,38 @@ cent-account scaling, so check the first result against your terminal. Also: `re
 | `balance`, `equity`, `margin`, `free_margin`, `margin_level`, `profit` | the same figures as cheap reads from the cache (no refresh; the margin may still wait for a conversion pair's first tick) |
 | `orders()` / `positions()` / `pending_orders()` / `order(ticket)` | `list[Order]` working / open positions / pending / one |
 | `history(start, end)` | `list[Order]` — closed orders and balance / credit entries, by close time |
-| `summary(start=None, end=None)` | `AccountSummary` — realized profit, deposits, withdrawals |
+| `summary(start, end)` | `AccountSummary` — realized profit, deposits, withdrawals |
 | `equity_history(start, "D1")` | `list[EquityPoint]` — balance (exact) and equity (reconstructed) curve with drawdowns |
 
 MT4 keeps one record for open positions, pending orders, closed orders and ledger entries: `Order.order_type` tells
 them apart (`Buy` / `Sell`, `BuyLimit` … , `Balance` / `Credit`), and `is_market`, `is_pending`, `is_capital_flow`
 say it directly. Times are naive `datetime` values in the **broker's server time**; 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()` runs from its
+start to now, so its 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"
+closed = c.history(end - timedelta(days=30), end)
+year = c.summary(end - timedelta(days=365), end)
+```
+
 `history()`, `summary()` and `equity_history()` each open their own short-lived broker connection and cost one
 licence request, which the licence service rate-limits per minute: fetch once and reuse the result. `history()`
-takes a `threading.Event` as `cancel=` to abandon the wait.
+takes a `threading.Event` as `cancel=` to abandon the wait. A window with no closed order in it gives a flat equity
+curve at the balance, never an empty one.
 
 ## Events
 
 `on_quote`, `on_order_update`, `on_order_progress`, `on_connect`, `on_disconnect`, `on_quote_history`,
 `on_symbols_update` — each returns a function that removes the callback. `quotes()`, `order_updates()` and
-`order_progress()` (and the `a…` async versions) turn a stream into an iterator.
+`order_progress()` (and the `a…` async versions) turn a stream into an iterator. Events reach you in the order the
+server sent them — a ticket's open before its modifications and its close — and callbacks run one at a time on the
+client's own thread.
 
 ## Staying connected
 
@@ -224,15 +260,23 @@ 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`) | — |
+| 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 `WMT4API_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. The MT4 core has no proxy support.
 
+**These two settings decide what code runs in your process.** `WMT4API_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
@@ -245,7 +289,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.2.0}/examples/pnl.py

@@ -13,10 +13,12 @@ with Client(int(os.environ["PMT4_LOGIN"]), os.environ["PMT4_PASSWORD"], os.envir
     print("balance %.2f  equity %.2f  floating %.2f  margin %.2f  free %.2f"
           % (a.balance, a.equity, a.profit, a.margin, a.free_margin))
 
-    s = c.summary()                                   # from the closed-order 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(c.server_time - timedelta(days=30), "D1")
+    curve = c.equity_history(now - timedelta(days=30), "D1")
     for p in curve[-5:]:
         print("%s  balance %.2f  equity %.2f  drawdown %.2f%%"
               % (p.time.strftime("%Y-%m-%d %H:%M"), p.balance, p.equity, p.equity_drawdown_relative * 100))

{pmt4api-1.0.0 → pmt4api-1.2.0}/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.2.0"
 
 __all__ = [
     "Client",

{pmt4api-1.0.0 → pmt4api-1.2.0}/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.2.0}/src/pmt4api/_account.py

@@ -4,15 +4,22 @@ from __future__ import annotations
 import asyncio
 import functools
 import threading
-from datetime import datetime, timedelta, timezone
+from datetime import datetime
 from typing import Any, List, Optional
 
 from ._base import _Base
 from ._util import enum_value, to_core_time, translated
-from .errors import NotConnectedError, RequestCancelled
+from .errors import InvalidRequestError, NotConnectedError, RequestCancelled
 from .models import AccountInfo, AccountSummary, EquityPoint, Order, _time
 
 
+def _history_days(days: Any) -> int:
+    """A ``max_history_days`` value: a whole number of days, 0 for no limit."""
+    if isinstance(days, bool) or not isinstance(days, int) or days < 0:
+        raise ValueError("max_history_days must be a whole number of days, or 0 for no limit (got %r)" % (days,))
+    return days
+
+
 class _Cancellation:
     """Turns a :class:`threading.Event` into the core's ``CancellationToken`` for the duration of one call."""
 
@@ -173,27 +180,24 @@ class _AccountMixin(_Base):
     # ---- history -----------------------------------------------------------------------------------------------
 
     @translated
-    def history(self, start: Optional[datetime] = None, end: Optional[datetime] = None,
-                timeout: Optional[float] = None, cancel: Optional[threading.Event] = None) -> List[Order]:
-        """Closed orders and balance / credit entries between ``start`` and ``end`` (default: the last 30 days up to
-        now), sorted by close time. Blocks until the server has sent everything, up to ``timeout`` seconds (default:
-        the client's ``history_timeout``); set the ``cancel`` event to abandon the wait early
-        (:class:`RequestCancelled`).
+    def history(self, start: datetime, end: datetime, timeout: Optional[float] = None,
+                cancel: Optional[threading.Event] = None) -> List[Order]:
+        """Closed orders and balance / credit entries between ``start`` and ``end``, sorted by close time. Blocks until
+        the server has sent everything, up to ``timeout`` seconds (default: the client's ``history_timeout``); set the
+        ``cancel`` event to abandon the wait early (:class:`RequestCancelled`).
+
+        Both ends are required and the window may be at most :attr:`max_history_days` long (366 by default): a missing,
+        reversed or longer window raises :class:`InvalidRequestError` before anything is sent. For a longer period,
+        call once per window and add the results up. For "up to now", pass ``c.server_time`` as ``end``.
 
         Naive datetimes are used exactly as given, in the broker's server time; timezone-aware ones are converted to
-        it. The default window is computed on the server's clock.
+        it.
 
         Each call opens its own short-lived broker connection and costs one licence request, which the licence
         service rate-limits per minute: fetch once and reuse the result rather than polling.
         """
         self._require_connected()
-        now = self.server_time or datetime.now(timezone.utc).replace(tzinfo=None)
-        end = self._server_naive(end)
-        start = self._server_naive(start)
-        if end is None:
-            end = now + timedelta(days=1)            # nothing the server has booked is later than this
-        if start is None:
-            start = now - timedelta(days=30)
+        start, end = self._window(start, end, "history")
         ms = int(timeout * 1000) if timeout is not None else int(self._api.DownloadOrderHistoryTimeoutMs)
         if ms <= 0:
             raise ValueError("timeout must be positive")
@@ -206,8 +210,7 @@ class _AccountMixin(_Base):
                 rows = self._api.DownloadOrderHistory(to_core_time(start), to_core_time(end), ms)
         return [Order._from_core(o) for o in (rows or ())]
 
-    async def ahistory(self, start: Optional[datetime] = None, end: Optional[datetime] = None,
-                       timeout: Optional[float] = None) -> List[Order]:
+    async def ahistory(self, start: datetime, end: datetime, timeout: Optional[float] = None) -> List[Order]:
         """Awaitable :meth:`history`. Cancelling the awaiting task abandons the download (the broker connection it
         opened is closed), so ``asyncio.wait_for(c.ahistory(...), 10)`` does not leave a request running."""
         cancel = threading.Event()
@@ -220,32 +223,55 @@ class _AccountMixin(_Base):
             cancel.set()
             raise
 
+    @property
+    def max_history_days(self) -> int:
+        """The longest window, in days, one :meth:`history`, :meth:`summary` or :meth:`equity_history` call may ask
+        for (default 366). A longer window raises :class:`InvalidRequestError` before anything is sent: split the
+        period into several calls, or raise this when you mean one long download. ``0`` removes the limit (the start
+        and end are still required)."""
+        return int(self._api.MaxHistoryDays)
+
+    @max_history_days.setter
+    def max_history_days(self, days: int) -> None:
+        self._api.MaxHistoryDays = _history_days(days)
+
+    def _window(self, start: Optional[datetime], end: Optional[datetime], what: str) -> tuple:
+        """``start`` and ``end`` in server time; both are required (the length is checked by the core)."""
+        if start is None or end is None:
+            raise InvalidRequestError("%s() needs a start and an end: history is always asked for by window "
+                             "(at most max_history_days, %d days, per call)" % (what, self.max_history_days))
+        return self._server_naive(start), self._server_naive(end)
+
     # ---- realized figures and curves ---------------------------------------------------------------------------
 
     @translated
-    def summary(self, start: Optional[datetime] = None, end: Optional[datetime] = None) -> AccountSummary:
-        """Realized trading result, deposits and withdrawals, from the closed-order ledger (all time by default).
+    def summary(self, start: datetime, end: datetime) -> AccountSummary:
+        """Realized trading result, deposits and withdrawals between ``start`` and ``end``, from the closed-order
+        ledger. Both ends are required; the window may be at most :attr:`max_history_days` long — for a longer period,
+        add up one summary per window (``balance`` is the account's current balance in each).
 
         Downloads the history, so it blocks and costs one licence request; call it off your UI thread (or use
         ``asyncio.to_thread``).
         """
         self._require_connected()
-        if start is None and end is None:
-            return AccountSummary._from_core(self._api.GetAccountSummary())
-        if start is None or end is None:
-            raise ValueError("give both start and end, or neither")
-        return AccountSummary._from_core(self._api.GetAccountSummary(to_core_time(self._server_naive(start)),
-                                                                     to_core_time(self._server_naive(end))))
+        start, end = self._window(start, end, "summary")
+        return AccountSummary._from_core(self._api.GetAccountSummary(to_core_time(start), to_core_time(end)))
 
     @translated
     def equity_history(self, start: datetime, timeframe: str = "D1", exclude_same_bars: bool = True) -> List[EquityPoint]:
-        """The balance and equity curve since ``start`` (``timeframe`` is ``H1``, ``H4`` or ``D1``).
+        """The balance and equity curve from ``start`` to now (``timeframe`` is ``H1``, ``H4`` or ``D1``); ``start``
+        may be at most :attr:`max_history_days` ago.
 
         ``balance`` is exact; the historical ``equity`` is a reconstruction priced from the symbols' bars. With
         ``exclude_same_bars`` (the default, as in the C# library) consecutive points with an unchanged balance and
-        equity are dropped. Downloads the history and per-symbol bars, so it blocks and costs a licence request.
+        equity are dropped. A window with no closed order in it is a flat line at the balance (never empty); the last
+        point is the live balance and equity. Downloads the history and per-symbol bars, so it blocks and costs a
+        licence request.
         """
         self._require_connected()
+        if start is None:
+            raise InvalidRequestError("equity_history() needs a start (at most max_history_days, %d days, ago)"
+                             % self.max_history_days)
         tf = enum_value(self._core.EquityTimeframe, timeframe, "equity timeframe")
         with self._bars_lock:                    # it downloads bars through the same single-flight request as bars()
             points = self._api.CalculateEquityHistory(to_core_time(self._server_naive(start)), tf,