diff --git a/CHANGELOG.md b/CHANGELOG.md index 58cb03b..d59c29d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,20 @@ All notable changes to this project are documented here. The format follows ## [Unreleased] +### Fixed +- A defaulted `close_positions()` / `cancel_pending_orders()` that matched + nothing dropped a failure of its follow-up check for items with other magics + left open, so `Ok([])` could read as "flat" in silence on a netting account. + It now logs a warning that it could not check. + +### Changed +- README: a table of contents, an index of every ADR, and the essentials in + one place: connecting, magic-number scope (symbol, ticket, magic 0 on a + single-bot account, netting), error kinds with what to do, batch failures, + and a checklist before trading real money. The README may have up to 600 + lines; every other file keeps the 300-line limit. Links to other documents + are absolute GitHub URLs, so they also work on PyPI. + ## [3.0.0] - 2026-11-09 Complete rewrite. See [MIGRATION.md](MIGRATION.md) for every behaviour change. diff --git a/README.md b/README.md index 6c1045e..02e9716 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,45 @@ A safe, typed trading layer over the official [`MetaTrader5`](https://pypi.org/project/MetaTrader5/) Python package. Built for bots (webhook executors, signal followers) where a trading call must -**never hang, never retry blindly, and never fail silently**: +**never hang, never retry blindly, and never fail silently**. + +## Contents + +- [Why this library](#why-this-library) +- [Requirements and limits](#requirements-and-limits) +- [Installation](#installation) +- [Quick start](#quick-start) +- [Connecting](#connecting) +- [Opening positions and limit orders](#opening-positions-and-limit-orders) + - [Stops: SL and TP](#stops-sl-and-tp) + - [Volumes, prices and comments](#volumes-prices-and-comments) +- [Closing and cancelling](#closing-and-cancelling) + - [Magic numbers: whose trades a call touches](#magic-numbers-whose-trades-a-call-touches) + - [Symbol and ticket](#symbol-and-ticket) + - [One bot per account and magic 0](#one-bot-per-account-and-magic-0) + - [Netting accounts](#netting-accounts) +- [Reading positions and orders](#reading-positions-and-orders) +- [Results and errors](#results-and-errors) + - [Error kinds](#error-kinds) + - [Retries](#retries) + - [Batch failures](#batch-failures) +- [Logging](#logging) +- [Calling MetaTrader5 functions directly](#calling-metatrader5-functions-directly) +- [Migrating from 2.x](#migrating-from-2x) +- [Before trading real money](#before-trading-real-money) +- [Architecture and decisions (ADR)](#architecture-and-decisions-adr) +- [Development](#development) +- [License](#license) + +Links to the other documents point to GitHub. On PyPI the Contents entries +above do not jump to their sections; read this page on +[GitHub](https://github.com/Akinzou/MetaTrader5-Python#contents) for that. + +Other documents: [CHANGELOG.md](https://github.com/Akinzou/MetaTrader5-Python/blob/master/CHANGELOG.md) · +[MIGRATION.md](https://github.com/Akinzou/MetaTrader5-Python/blob/master/MIGRATION.md) · [docs/architecture.md](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/architecture.md) · +[docs/adr](https://github.com/Akinzou/MetaTrader5-Python/tree/master/docs/adr) + +## Why this library - **Every trading call returns.** Requotes are retried a bounded number of times with a fresh quote; everything else comes back immediately as a typed error. @@ -26,22 +64,29 @@ Built for bots (webhook executors, signal followers) where a trading call must (`MARKET_CLOSED`, `NO_MONEY`, `INVALID_STOPS`, ...) instead of magic numbers. - **Correct prices and lots.** Prices snap to the symbol's tick grid, volumes are checked against min/max/step, the filling mode is chosen from the symbol. -- **Magic numbers.** Tag your bot's trades and close/cancel only those. +- **Close-all touches only your bot's magic.** `close_positions()` and + `cancel_pending_orders()` act on the trader's own magic number unless told + otherwise. With the default `magic=0` that includes manual trades: set your + own `magic` ([details](#one-bot-per-account-and-magic-0)). - **SL/TP as prices or distances in points.** - **2.x compatible.** The old `Broker` class still works (deprecated). -> One connection per process: the official package keeps a single global -> terminal session, so a second `connect()` (or its failed login) affects the -> first. Run one process per account. -> -> Thread-safe within the library: every terminal call holds one process-wide -> lock, so a threaded webhook server can share a `Trader`. The MT5 functions -> re-exported through `PythonMetaTrader5` hold it for each single call (a pair -> such as `order_send` + `last_error` is not atomic). Calls you make to the -> `MetaTrader5` module directly bypass it. -> -> Requires Windows with a MetaTrader 5 terminal installed (the official -> `MetaTrader5` package is Windows-only). Enable **Algo Trading** in the terminal. +## Requirements and limits + +- **Windows** with a MetaTrader 5 terminal installed: the official + `MetaTrader5` package is Windows-only. Python **3.10+**. +- **Algo Trading** must be enabled in the terminal. Without it every order + fails with `ALGO_TRADING_DISABLED`. The library does not toggle it for you + ([ADR 0004](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0004-no-gui-automation.md)). +- **One connection per process.** The official package keeps a single global + terminal session, so a second `connect()` (or its failed login) affects the + first. Run one process per account. +- **Thread-safe within the library.** Every terminal call holds one + process-wide lock, so a threaded webhook server can share a `Trader` + ([ADR 0009](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0009-one-lock-per-process.md)). The MT5 functions + re-exported through `PythonMetaTrader5` hold it for each single call (a pair + such as `order_send` + `last_error` is not atomic). Calls you make to the + `MetaTrader5` module directly bypass it. ## Installation @@ -49,6 +94,8 @@ Built for bots (webhook executors, signal followers) where a trading call must pip install PythonMetaTrader5 ``` +To stay on the old API: `pip install "PythonMetaTrader5<3"`. + ## Quick start ```python @@ -76,13 +123,28 @@ with trader: # shuts the terminal connection down on exit trader.close_positions("EURUSD") # only this bot's (magic 1001) positions ``` -## API +## Connecting + +```python +connect(login, password, server, *, path=None, timeout_ms=60000, magic=0, + deviation=10, retry=None) -> Result[Trader, TradeError] +``` + +| Argument | Meaning | +|---|---| +| `login` | Account number: a positive integer or a string of ASCII digits. `True`, `12345678.9` and similar values are rejected, not coerced | +| `password`, `server` | As in the terminal's login dialog, e.g. `"MetaQuotes-Demo"` | +| `path` | Path to `terminal64.exe` when more than one terminal is installed | +| `timeout_ms` | How long the terminal may take to start and log in | +| `magic` | The bot's own magic number, an integer from 0 to 2\*\*64-1. Every order is tagged with it, and close-all/cancel-all act only on it ([see below](#magic-numbers-whose-trades-a-call-touches)). Anything else, `None` included, returns `Err(INVALID_ARGUMENT)` | +| `deviation` | Maximum accepted slippage in points for market orders | +| `retry` | A `RetryPolicy` ([see Retries](#retries)) | -`connect(login, password, server, *, path=None, timeout_ms=60000, magic=0, -deviation=10, retry=None) -> Result[Trader, TradeError]` +`connect()` never raises for a failed login: it returns +`Err(TradeError(CONNECTION_FAILED, ...))`. A `Trader` is a context manager; +`with trader:` calls `shutdown()` on exit. -`login` must be a positive integer or a string of ASCII digits; `True`, -`12345678.9` and similar values are rejected rather than coerced. +## Opening positions and limit orders | `Trader` method | Returns | |---|---| @@ -94,52 +156,162 @@ deviation=10, retry=None) -> Result[Trader, TradeError]` | `pending_orders(symbol=None, *, magic=None, kind=None)` | `Result[list[PendingOrder], TradeError]` | | `shutdown()` | `None` | -- `side`: `Side.BUY` / `Side.SELL`, or the strings `"buy"`, `"sell"`, `"long"`, `"short"`. -- `sl` / `tp`: a float is an **absolute price**; `Stop.points(n)` is a distance - of `n` points from the entry price (`Stop.at_price(p)` is the explicit form). - For limit orders the distance is measured from the limit price, and for a - market order with an explicit `price` from that price. A float stop that is - zero, negative or not finite is rejected (`INVALID_STOPS`); pass `None` for - no stop. `Stop.points()` / `Stop.at_price()` raise `ValueError` unless the - value is a positive finite number (bool and str included; a zero stop would - mean "no stop" to MT5); the sign of a points distance is ignored. A `kind` - that is not a `StopKind` raises `TypeError`. A stop that resolves outside - the tick grid's range, or to zero or below, is `INVALID_STOPS` when the - order is built. For a value that may be bad at runtime, such as - an ATR that is NaN during warm-up, use - `Stop.parse(value, StopKind.POINTS)`, which returns `Ok(stop)` / - `Err(INVALID_STOPS)`. +- `side`: `Side.BUY` / `Side.SELL`, or the strings `"buy"`, `"sell"`, `"long"`, + `"short"`. +- A market order is built from the **current** quote; `price=` sends it once at + that price instead. +- The filling mode comes from the symbol's allowed modes (FOK, then IOC, then + RETURN); limit orders on exchange-execution symbols use RETURN + ([ADR 0007](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0007-filling-and-price-grid.md)). + +### Stops: SL and TP + +- A float is an **absolute price**; `Stop.points(n)` is a distance of `n` + points from the entry price (`Stop.at_price(p)` is the explicit form). +- For limit orders the distance is measured from the limit price, and for a + market order with an explicit `price` from that price. +- Pass `None` for no stop. A float stop that is zero, negative or not finite is + rejected (`INVALID_STOPS`): MT5 would read 0 as "no stop" + ([ADR 0008](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0008-refuse-values-mt5-misreads.md)). +- `Stop.points()` / `Stop.at_price()` raise `ValueError` unless the value is a + positive finite number (bool and str included); the sign of a points distance + is ignored. A `kind` that is not a `StopKind` raises `TypeError`. +- A stop that resolves outside the tick grid's range, or to zero or below, is + `INVALID_STOPS` when the order is built. +- For a value that may be bad at runtime, such as an ATR that is NaN during + warm-up, use `Stop.parse(value, StopKind.POINTS)`, which returns `Ok(stop)` / + `Err(INVALID_STOPS)` instead of raising. + +### Volumes, prices and comments + - Amounts may be `int`, `float`, `Decimal` or numpy scalars; `bool` and strings are refused (the deprecated `Broker` still converts numeric strings). -- `price` (market orders): send at this price once instead of the live quote. -- `comment`: at most 29 UTF-16 units: 29 characters, but characters outside - the BMP, such as most emoji, count as 2 (combined emoji more). The `MetaTrader5` package refuses 30 or more (measured on 5.0.6231; its - docs say 31). Longer comments, and comments that are not `str`, are rejected - before sending, not truncated. -- **`close_positions()` and `cancel_pending_orders()` act only on the trader's - own `magic`** unless you pass another one (ADR 0011); `magic=None` is still - "own". To act on the whole account, manual trades included, pass - `magic=ANY_MAGIC`. A `ticket` is closed whatever its magic. `positions()` - and `pending_orders()` still list every magic by default. -- Manual trades have magic 0, the `connect()` default, so set your own `magic` - for this to protect them. Until then a close/cancel that affects magic-0 - items logs a warning; `magic=0` passed explicitly acknowledges it. On a - netting account a position keeps the magic of the deal that opened it, so - merged volume cannot be told apart by magic; a defaulted close/cancel that - matches nothing logs how many items with other magics it left open. -- A magic must be an integer from 0 to 2\*\*64-1 (MT5's ulong); `connect()` - returns `Err(INVALID_ARGUMENT)` otherwise, e.g. for `None`. An empty string - `""` as symbol is rejected too. -- `BatchFailure.errors` names every position/order that failed - (`TradeError.ticket`). `BatchFailure.succeeded` holds the receipts of the - ones that worked; their `order` / `deal` are the IDs of the closing deal, not - the position ticket. -- `ticket` must be a positive integer; `0`, `True` or `"7"` are rejected. - -### Errors +- Volumes are checked against the symbol's min, max and step before sending + (`INVALID_VOLUME`). Prices snap to the symbol's tick size, not just `digits`, + so symbols with a tick of 0.25 work. +- `comment`: at most 29 UTF-16 units: 29 characters, but characters outside the + BMP, such as most emoji, count as 2 (combined emoji more). The `MetaTrader5` + package refuses 30 or more (measured on 5.0.6231; its docs say 31). Longer + comments, and comments that are not `str`, are rejected before sending + (`INVALID_ARGUMENT`), not truncated. + +## Closing and cancelling + +### Magic numbers: whose trades a call touches + +A magic number tags every order a bot sends. MT5 gives trades opened by hand +magic **0**. Decision and reasoning: +[ADR 0011](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0011-close-all-defaults-to-own-magic.md). + +| Call | Acts on | +|---|---| +| `close_positions()` / `cancel_pending_orders()` | Only the trader's own magic (the one given to `connect()`) | +| `...(magic=None)` | Still only the own magic: a `None` from a missing config key cannot widen the call | +| `...(magic=7)` | Only magic 7 | +| `...(magic=ANY_MAGIC)` | Every magic on the account, manual trades included | +| `close_positions(ticket=t)` | Position `t`, whatever its magic: you named it. With `magic=` too, `t` closes only if its magic matches | +| `positions()` / `pending_orders()` | Every magic by default: a read cannot close anything | + +A magic must be an integer from 0 to 2\*\*64-1 (MT5's ulong). `"42"`, `True`, +`1.5`, `-1` and `2**64` are refused as `INVALID_ARGUMENT` instead of matching +nothing and reporting an empty success. + +```python +from PythonMetaTrader5 import ANY_MAGIC + +trader.close_positions() # this bot's positions only +trader.close_positions(magic=ANY_MAGIC) # the whole account +``` + +### Symbol and ticket + +- `symbol` limits a call to that symbol exactly: `close_positions("EURGBP")` + never touches a EURUSD position, also with `magic=ANY_MAGIC`. The adapter + re-checks the symbol of every position MT5 returns. +- `ticket` takes precedence over `symbol`, as in 2.x: + `close_positions("EURGBP", ticket=t)` closes position `t` even if it is on + EURUSD. +- `ticket` must be a positive integer; `0`, `True` or `"7"` are rejected (0 may + mean "no filter" to MT5). An empty string `""` as symbol is rejected too: a + missing webhook field must not mean "every symbol". +- `cancel_pending_orders(kind=PendingKind.LIMIT)` limits a cancel to one order + type (`LIMIT`, `STOP`, `STOP_LIMIT`). +- Each position is closed on its own symbol with its own spec, and a symbol + with broken data can still be closed. + +### One bot per account and magic 0 + +`connect()` keeps `magic=0` as its default, so a bot that is alone on its +account works without setting one. The cost: manual trades share magic 0, so +such a bot's close-all also closes manual positions and cancels manual pending +orders. Whenever a defaulted close/cancel of a magic-0 trader affects +something, the library logs a warning: + +``` +trader magic is 0, which manual trades share: this close/cancel includes them; set magic at connect(), or pass magic=0 to confirm +``` + +- Bot alone on the account and the behaviour is intended: pass `magic=0` + explicitly (`close_positions(magic=0)`) and the warning is not logged. +- Bot next to manual trading or other bots: give it its own magic in + `connect(..., magic=1001)`. + +### Netting accounts + +On a netting account one position per symbol collects every deal and keeps the +magic of the deal that opened it, so merged volume cannot be told apart by +magic. A bot's deal that merges into a manual position is not "own"; a manual +deal that merges into the bot's position is. When a defaulted close/cancel +matches nothing while items with other magics are in scope, the library logs +how many it left open, so `Ok([])` never reads as "flat" in silence. If that +extra listing fails, the warning says it could not check. + +## Reading positions and orders + +- `Position`: `ticket`, `symbol`, `side`, `volume`, `price_open`, `sl`, `tp` + (`None` when not set), `price_current`, `profit`, `swap`, `time`, `magic`, + `comment`, and MT5's `identifier`, `reason`, `time_msc`, `time_update`, + `time_update_msc`, `external_id`. +- `PendingOrder`: `ticket`, `symbol`, `side`, `kind` (`PendingKind`), `volume`, + `price`, `magic`, `comment`. +- `TradeReceipt` (the broker's answer): `retcode`, `deal`, `order`, `volume`, + `price`, `bid`, `ask`, `comment`, `request_id`, `retcode_external`. For a + close, `order` / `deal` are the IDs of the closing deal, not the position + ticket. +- An empty account is `Ok([])`; a terminal failure is `Err(TERMINAL_ERROR)`, + never an empty list. + +## Results and errors + +Expected failures are values, not exceptions +([ADR 0002](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0002-result-at-boundaries.md)): every call returns `Ok(...)` +or `Err(...)`. Exceptions are reserved for programming errors such as +`RetryPolicy(attempts=0)` or `Stop.points("x")`. `TradeError(kind, message, retcode=None, receipt=None, ticket=None)`. The -`receipt` carries the broker's raw answer when there was one. Retry policy: +`receipt` carries the broker's raw answer when there was one; `ticket` names the +position/order in a batch. + +### Error kinds + +| `ErrorKind` | Meaning | What to do | +|---|---|---| +| `INVALID_ARGUMENT`, `INVALID_VOLUME`, `INVALID_PRICE`, `INVALID_STOPS` | Refused before sending, or by the server for the same reason | Fix the input; a resend gives the same answer | +| `INVALID_FILLING` | The server refused the filling mode the library chose from the symbol's flags (10030) | Nothing to fix in your call: escalate to the broker; a resend gives the same answer | +| `NO_MONEY`, `LIMIT_REACHED` | Margin or a broker limit | Do not resend unchanged | +| `MARKET_CLOSED`, `TRADE_DISABLED` | The symbol cannot be traded now | Wait or skip | +| `ALGO_TRADING_DISABLED` | Algo Trading is off in the terminal (10027) or on the server (10026) | 10027: enable it in the terminal. 10026: the broker or account forbids it; contact the broker | +| `PARTIAL_FILL` | Part of the volume executed | Check `positions()`; never re-sent | +| `OUTCOME_UNKNOWN` | Timeout, lost connection, or a queued market deal | **Check `positions()` before anything else**: the order may be live | +| `RETRIES_EXHAUSTED` | Requotes/price changes outlasted the retry policy | Retry later with a fresh decision | +| `REJECTED` | Any other server refusal (also unknown retcodes) | Read `message` and `retcode` | +| `SYMBOL_NOT_FOUND`, `NO_PRICE` | Unknown symbol, or no quote | Check the symbol name and market data | +| `BROKEN_SYMBOL_DATA` | The terminal's symbol data cannot price an order (point 0, NaN tick size, volume step 0) | Escalate; a resend gives the same answer. Closing still works | +| `TERMINAL_ERROR`, `CONNECTION_FAILED` | The terminal or the login failed | Check the terminal and credentials | + +### Retries + +[ADR 0003](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0003-bounded-retries.md): | Server answer | What happens | |---|---| @@ -150,7 +322,8 @@ deviation=10, retry=None) -> Result[Trader, TradeError]` | requote, price changed, no quotes, too many requests | retried with a fresh quote, up to `RetryPolicy.attempts` (default 3, 0.5 s apart), then `RETRIES_EXHAUSTED` | | timeout, no connection, or `order_send` lost in IPC | `OUTCOME_UNKNOWN`, never retried: check `positions()` first | | anything else | the matching `ErrorKind`, returned at once | -| refused before sending: the terminal's symbol data cannot price an order (point 0, NaN tick size, volume step 0, ...) | `BROKEN_SYMBOL_DATA`, the same on every resend: escalate, don't retry. Closing still works on such symbols | +| refused before sending: no quote yet (`NO_PRICE`, e.g. a symbol just added to Market Watch) | waited for and rebuilt up to `RetryPolicy.attempts`, then `NO_PRICE`; nothing was sent | +| refused before sending: anything else | the matching `ErrorKind`, returned at once; nothing was sent | ```python from PythonMetaTrader5 import RetryPolicy, connect @@ -158,18 +331,102 @@ from PythonMetaTrader5 import RetryPolicy, connect connect(..., retry=RetryPolicy(attempts=5, delay_seconds=0.2)) ``` -### Logging +### Batch failures + +`close_positions()` and `cancel_pending_orders()` try every matching item and +return `Ok(receipts)` only when all succeeded (`Ok([])` when nothing matched). +Otherwise they return `Err(BatchFailure)`: + +- `BatchFailure.succeeded`: receipts of the items that worked. +- `BatchFailure.errors`: one `TradeError` per item that failed, with + `TradeError.ticket` naming it. +- When the call fails before trying any item (an invalid `magic` or `comment`, + or the listing itself fails), `succeeded` is empty and the single error has + `ticket=None`. +- A failed item is not necessarily still open: `OUTCOME_UNKNOWN` may have + closed it and `PARTIAL_FILL` closed part of it. Read `positions()` before + sending again. + +```python +from PythonMetaTrader5 import ErrorKind + +match trader.close_positions("EURUSD"): + case Ok(receipts): + print("closed", len(receipts)) + case Err(failure): + for error in failure.errors: + if error.ticket is None: + print("nothing tried:", error.kind, error.message) + elif error.kind in (ErrorKind.OUTCOME_UNKNOWN, ErrorKind.PARTIAL_FILL): + print("check positions():", error.ticket, error.kind) + else: + # REJECTED also covers "position already closed" (10036). + print("not closed by this call:", error.ticket, error.kind, error.message) +``` + +## Logging The library logs through the standard `logging` module under the -`PythonMetaTrader5` logger and never configures handlers itself. Without any -logging configuration, warnings and errors still reach stderr. +`PythonMetaTrader5` logger and never configures handlers itself +([ADR 0005](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0005-stdlib-logging.md)). Without any logging +configuration, warnings and errors still reach stderr. The login and server are +logged on connect; the account owner's name and balance are not. + +## Calling MetaTrader5 functions directly + +As in 2.x, the `MetaTrader5` functions and constants are reachable through this +package, loaded lazily ([ADR 0010](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0010-keep-the-metatrader5-re-export.md)): + +```python +from PythonMetaTrader5 import * + +info = symbol_info("EURUSD") +print(ORDER_TYPE_BUY) +``` + +Names defined by this library win over MT5's (our `Tick` over MT5's struct). ## Migrating from 2.x `from PythonMetaTrader5 import Broker` keeps working and emits a -`DeprecationWarning`. `from PythonMetaTrader5 import *` still brings in the -`MetaTrader5` functions and constants, as in 2.x. Several 2.x behaviours were unsafe and changed: see -[MIGRATION.md](MIGRATION.md). +`DeprecationWarning` ([ADR 0006](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0006-legacy-facade.md)). `Broker` +keeps 2.x behaviour where it was safe: `Close` and `CancelOrders` still act on +every magic. Several 2.x behaviours were unsafe and changed: endless retries, +`sl=0` as "no stop", Ctrl+E automation, fixed filling modes and more. Read +[MIGRATION.md](https://github.com/Akinzou/MetaTrader5-Python/blob/master/MIGRATION.md) before upgrading a bot that trades real money; it +also maps the main `Broker` calls to their `Trader` equivalents. + +## Before trading real money + +- Run your bot on a **demo** account first. The library's own demo tests need + a source checkout ([Development](#development)); they are not in the wheel. +- Give every bot its own `magic` unless it is alone on the account. +- Treat `OUTCOME_UNKNOWN` as "maybe filled": read `positions()` before sending + again. +- Check `Err` on every call. A refused close leaves the position open; an + `OUTCOME_UNKNOWN` or `PARTIAL_FILL` close may have closed all or part of it, + so read `positions()` before acting again. +- Trading carries risk; this software comes without any warranty. + +## Architecture and decisions (ADR) + +Clean Architecture with Ports & Adapters: `domain/` holds the trading rules, +`application/` the use cases (`Trader`), `adapters/` the only code that talks +to MetaTrader 5. Details: [docs/architecture.md](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/architecture.md). + +| ADR | Decision | +|---|---| +| [0001](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0001-ports-only-at-process-boundaries.md) | Ports only at process boundaries | +| [0002](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0002-result-at-boundaries.md) | Result values at boundaries, exceptions for programming errors | +| [0003](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0003-bounded-retries.md) | Bounded retries, never on an unknown outcome | +| [0004](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0004-no-gui-automation.md) | No GUI automation for Algo Trading | +| [0005](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0005-stdlib-logging.md) | Standard logging, no NullHandler | +| [0006](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0006-legacy-facade.md) | Keep a 2.x `Broker` facade | +| [0007](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0007-filling-and-price-grid.md) | Filling mode from the symbol, prices on the tick grid | +| [0008](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0008-refuse-values-mt5-misreads.md) | Refuse input that MT5 would quietly read as something else | +| [0009](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0009-one-lock-per-process.md) | One lock per process around terminal calls | +| [0010](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0010-keep-the-metatrader5-re-export.md) | Keep re-exporting the MetaTrader5 namespace, lazily | +| [0011](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0011-close-all-defaults-to-own-magic.md) | Close-all and cancel-all default to the trader's own magic | ## Development @@ -179,6 +436,7 @@ pip install -e ".[dev]" ruff check src tests scripts && ruff format --check src tests scripts mypy pytest --cov +python scripts/check_file_length.py ``` `tests/contract` compares the unit-test fakes with the installed `MetaTrader5` @@ -187,10 +445,7 @@ Integration tests trade on a **demo** account and are skipped unless `MT5_LOGIN`, `MT5_PASSWORD` and `MT5_SERVER` are set (they refuse to run on a live account): `pytest -m integration`. -Architecture and decisions: [docs/architecture.md](docs/architecture.md), -[docs/adr](docs/adr). - ## License -[CC BY-NC 4.0](LICENSE). Trading carries risk; this software comes without any +[CC BY-NC 4.0](https://github.com/Akinzou/MetaTrader5-Python/blob/master/LICENSE). Trading carries risk; this software comes without any warranty. diff --git a/docs/adr/0011-close-all-defaults-to-own-magic.md b/docs/adr/0011-close-all-defaults-to-own-magic.md index 131328b..8f29986 100644 --- a/docs/adr/0011-close-all-defaults-to-own-magic.md +++ b/docs/adr/0011-close-all-defaults-to-own-magic.md @@ -55,7 +55,10 @@ gives trades opened by hand magic 0. a property of netting, not of this default. So that `Ok([])` never reads as "flat" in silence, a defaulted close/cancel that matches nothing while items with other magics are in scope logs a warning naming how many were - left open (one extra listing, only on that path). We did not detect the + left open (one extra listing, only on that path). If that listing fails, + the warning says so instead of dropping the error; the close/cancel stays + `Ok`, because it did what was asked and an `Err` would invite a retry of an + action that already ran. We did not detect the account's margin mode: it would add a port call for a case the warning already surfaces. - `application/magic_scope.py` holds the rule and its warnings, apart from diff --git a/scripts/check_file_length.py b/scripts/check_file_length.py index 0395dc9..1e051c9 100644 --- a/scripts/check_file_length.py +++ b/scripts/check_file_length.py @@ -9,6 +9,11 @@ MAX_LINES = 300 # Binary or third-party verbatim files; nothing generated is tracked. EXEMPT_SUFFIXES = {".png", ".jpg", ".ico", ".whl"} +# The owner's call (2026-11-09): the README is the landing page on GitHub and +# PyPI, so it keeps every essential behind a table of contents rather than +# sending readers through several pages. A higher ceiling, not none: an +# unbounded exemption would let a pasted log through. Only the top-level README. +LIMITS = {Path("README.md"): 600} def tracked_files() -> list[Path]: @@ -23,10 +28,11 @@ def main() -> int: for path in tracked_files(): if path.suffix in EXEMPT_SUFFIXES or not path.is_file(): continue + limit = LIMITS.get(path, MAX_LINES) count = len(path.read_text(encoding="utf-8", errors="replace").splitlines()) - if count > MAX_LINES: - offenders.append(f"{path}: {count} lines (limit {MAX_LINES})") - print("\n".join(offenders) or f"all tracked files have <= {MAX_LINES} lines") + if count > limit: + offenders.append(f"{path}: {count} lines (limit {limit})") + print("\n".join(offenders) or "all tracked files are within their line limits") return 1 if offenders else 0 diff --git a/src/PythonMetaTrader5/application/magic_scope.py b/src/PythonMetaTrader5/application/magic_scope.py index 7f7e559..364f587 100644 --- a/src/PythonMetaTrader5/application/magic_scope.py +++ b/src/PythonMetaTrader5/application/magic_scope.py @@ -55,7 +55,17 @@ def warn_about_default( # that kept another magic, and Ok([]) alone would read as "flat". The extra # listing runs only on this path. others = everything() - if isinstance(others, Ok) and others.value: + if not isinstance(others, Ok): + # Not turned into an Err: the close/cancel itself did what was asked, + # and failing it would make a bot retry an action that already ran. + log.warning( + "nothing with magic %s to close/cancel, and could not check for items " + "with other magics left open: %s", + own, + others.error, + ) + return + if others.value: log.warning( "nothing with magic %s to close/cancel; %d item(s) with other magics " "left open (on netting a deal merges into a position that keeps its " diff --git a/tests/unit/test_check_file_length.py b/tests/unit/test_check_file_length.py new file mode 100644 index 0000000..c91b1ab --- /dev/null +++ b/tests/unit/test_check_file_length.py @@ -0,0 +1,56 @@ +"""The line-limit guard that CI runs over every tracked file.""" + +from __future__ import annotations + +import importlib.util +from pathlib import Path +from types import ModuleType + +import pytest + +SCRIPT = Path(__file__).resolve().parents[2] / "scripts" / "check_file_length.py" + + +def load_script() -> ModuleType: + spec = importlib.util.spec_from_file_location("check_file_length", SCRIPT) + assert spec is not None + assert spec.loader is not None + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +def run_on(tmp_path: Path, monkeypatch: pytest.MonkeyPatch, name: str, lines: int) -> int: + script = load_script() + target = tmp_path / name + target.parent.mkdir(parents=True, exist_ok=True) + target.write_text("x\n" * lines, encoding="utf-8") + monkeypatch.chdir(tmp_path) + monkeypatch.setattr(script, "tracked_files", lambda: [Path(name)]) + return script.main() + + +def test_a_long_hand_written_file_fails( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + code = run_on(tmp_path, monkeypatch, "docs/guide.md", 301) + assert code == 1 + assert "guide.md: 301 lines" in capsys.readouterr().out + + +def test_the_readme_may_be_longer(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + assert run_on(tmp_path, monkeypatch, "README.md", 600) == 0 + + +def test_the_readme_still_has_a_ceiling( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + assert run_on(tmp_path, monkeypatch, "README.md", 601) == 1 + assert "README.md: 601 lines (limit 600)" in capsys.readouterr().out + + +def test_only_the_top_level_readme_is_exempt( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + code = run_on(tmp_path, monkeypatch, "docs/README.md", 301) + assert code == 1 diff --git a/tests/unit/test_own_magic.py b/tests/unit/test_own_magic.py index 94b742e..2c4f4d9 100644 --- a/tests/unit/test_own_magic.py +++ b/tests/unit/test_own_magic.py @@ -16,6 +16,7 @@ connect, ) from PythonMetaTrader5.application.trader import Trader +from PythonMetaTrader5.domain.errors import TradeError from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest from PythonMetaTrader5.result import Err, Ok @@ -240,6 +241,20 @@ def test_a_default_close_that_matches_nothing_says_what_it_left_open( assert terminal.sent == [] +def test_a_failed_check_for_items_left_open_is_logged_not_dropped( + trader: Trader, terminal: FakeTerminal, caplog: pytest.LogCaptureFixture +) -> None: + # The own listing is empty, then the listing of every magic fails: Ok([]) + # alone would read as "flat" with a merged netting position still open. + answers = iter([Ok([]), Err(TradeError(ErrorKind.TERMINAL_ERROR, "IPC timeout"))]) + terminal.positions = lambda **_: next(answers) # type: ignore[method-assign] + with caplog.at_level(logging.WARNING, logger="PythonMetaTrader5"): + assert trader.close_positions("EURUSD") == Ok([]) + (message,) = [r.getMessage() for r in caplog.records] + assert "could not check" in message + assert "IPC timeout" in message + + def test_no_left_open_warning_when_own_items_were_handled( trader: Trader, mixed_positions: FakeTerminal, caplog: pytest.LogCaptureFixture ) -> None: