From 9787c5d7d05dfefc02b73f4fe2b512f3151f38e7 Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 13:25:09 +0100 Subject: [PATCH] feat: close-all and cancel-all default to the trader's own magic (ADR 0011) Decided by the package owner: close_positions() / cancel_pending_orders() without a magic touch only the trader's own magic, with or without a symbol. The whole account is spelled magic=ANY_MAGIC; an explicit magic=None is still "own", so a None from a missing config key cannot widen the call. A ticket is closed whatever its magic (filtering it would return Ok([]) for a position the caller named). positions() / pending_orders() still list everything. Broker.Close / CancelOrders pass ANY_MAGIC to keep 2.x. A magic must be an integer from 0 to 2**64-1 (MT5's ulong): filters refuse "42", True, 1.5, -1 and 2**64 as INVALID_ARGUMENT; connect() returns Err and Trader() raises ValueError for an own magic that is None or ANY_MAGIC too, because connect(magic=None) made the "own" default mean "every magic". The default is never silent about what it cannot know: - a magic-0 trader (the connect() default, shared with manual trades) logs a warning when a defaulted close/cancel affects something; magic=0 passed explicitly acknowledges it; - a defaulted close/cancel that matches nothing while items with other magics are in scope logs how many it left open (netting merges deals into a position that keeps its first magic). The rule lives in application/magic_scope.py; trader.py stays under 300 lines. RED: tests/unit/test_own_magic.py failed for the default, None, ANY_MAGIC, invalid and out-of-range magics, connect/Trader validation and both warnings; ticket, explicit magic, Broker parity and symbol scoping passed before the change and guard it. Close-mechanics tests now give their positions the trader's own magic (42). Demo account: a position opened with another magic survives close_positions() and closes by ticket. Renamed test_cancel_removes_every_pending_order_of_the_symbol to test_cancel_removes_the_traders_own_pending_orders_of_the_symbol; removed Trader._own_unless_given / _warn_if_manual (moved to magic_scope). Repo-wide grep (excluding .venv/.git/caches): no matches. --- CHANGELOG.md | 5 + MIGRATION.md | 4 +- README.md | 23 +- .../0011-close-all-defaults-to-own-magic.md | 66 +++++ src/PythonMetaTrader5/__init__.py | 4 + src/PythonMetaTrader5/application/batch.py | 7 +- .../application/magic_scope.py | 65 +++++ src/PythonMetaTrader5/application/trader.py | 75 ++++- src/PythonMetaTrader5/connection.py | 6 +- src/PythonMetaTrader5/domain/inputs.py | 51 ++++ src/PythonMetaTrader5/legacy/broker.py | 7 +- tests/integration/test_demo_account.py | 48 +++ tests/unit/test_failure_paths.py | 2 +- tests/unit/test_own_magic.py | 274 ++++++++++++++++++ tests/unit/test_pending_orders.py | 5 +- tests/unit/test_safety_edges.py | 2 +- tests/unit/test_symbol_data.py | 2 +- 17 files changed, 614 insertions(+), 32 deletions(-) create mode 100644 docs/adr/0011-close-all-defaults-to-own-magic.md create mode 100644 src/PythonMetaTrader5/application/magic_scope.py create mode 100644 tests/unit/test_own_magic.py diff --git a/CHANGELOG.md b/CHANGELOG.md index b5fd8e1..7164d8a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,11 @@ Complete rewrite. See [MIGRATION.md](MIGRATION.md) for every behaviour change. values that may be bad at runtime; the constructors raise `ValueError`, and a `kind` that is not a `StopKind` raises `TypeError`. - Magic-number support for entries and as a filter for close/cancel/queries. + `close_positions()` / `cancel_pending_orders()` default to the trader's own + magic; `ANY_MAGIC` acts on the whole account; a `ticket` is closed whatever + its magic (ADR 0011). `Broker.Close` / `CancelOrders` keep acting on every + magic, as in 2.x. `connect(magic=...)` must be an integer from 0 to 2**64-1; a magic-0 + trader logs a warning when a close/cancel affects magic-0 (manual) trades. - Volume validation against the symbol's min/max/step. - Filling mode chosen from the symbol's allowed modes. - Hidden symbols are selected into Market Watch automatically. diff --git a/MIGRATION.md b/MIGRATION.md index a606018..eac0b99 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -99,9 +99,9 @@ logging.basicConfig(level=logging.INFO) | `Broker(login, password, server)` | `connect(login, password, server)` → `Ok(trader)` / `Err(error)` | | `OpenPosition(s, "buy", v, sl=1000, sl_type="offset")` | `trader.open_position(s, "buy", v, sl=Stop.points(1000))` | | `OpenPosition(s, "buy", v, sl=1.05)` | `trader.open_position(s, "buy", v, sl=1.05)` | -| `Close("EURUSD")` | `trader.close_positions("EURUSD")` | +| `Close("EURUSD")` | `trader.close_positions("EURUSD", magic=ANY_MAGIC)`; without `magic` only the trader's own positions close (ADR 0011) | | `BuyLimit(s, v, stoplimit=1.1)` | `trader.place_limit_order(s, "buy", v, 1.1)` (no automatic market fill when crossed) | -| `CancelOrders(s)` | `trader.cancel_pending_orders(s, kind=PendingKind.LIMIT)` | +| `CancelOrders(s)` | `trader.cancel_pending_orders(s, magic=ANY_MAGIC, kind=PendingKind.LIMIT)` | | `GetPositions(as_dict=True)` | see below | | `Disconnect()` | `trader.shutdown()` or `with trader:` | diff --git a/README.md b/README.md index 4789797..6c1045e 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ with trader: # shuts the terminal connection down on exit case Err(error): print("not opened:", error.kind, error.message) - trader.close_positions("EURUSD", magic=1001) # only this bot's positions + trader.close_positions("EURUSD") # only this bot's (magic 1001) positions ``` ## API @@ -88,8 +88,8 @@ deviation=10, retry=None) -> Result[Trader, TradeError]` |---|---| | `open_position(symbol, side, volume, *, sl=None, tp=None, price=None, comment=None)` | `Result[TradeReceipt, TradeError]` | | `place_limit_order(symbol, side, volume, price, *, sl=None, tp=None, comment=None)` | `Result[TradeReceipt, TradeError]` | -| `close_positions(symbol=None, *, ticket=None, magic=None, comment=None)` | `Result[list[TradeReceipt], BatchFailure]` | -| `cancel_pending_orders(symbol=None, *, magic=None, kind=None)` | `Result[list[TradeReceipt], BatchFailure]` | +| `close_positions(symbol=None, *, ticket=None, magic=, comment=None)` | `Result[list[TradeReceipt], BatchFailure]` | +| `cancel_pending_orders(symbol=None, *, magic=, kind=None)` | `Result[list[TradeReceipt], BatchFailure]` | | `positions(symbol=None, *, ticket=None, magic=None)` | `Result[list[Position], TradeError]` | | `pending_orders(symbol=None, *, magic=None, kind=None)` | `Result[list[PendingOrder], TradeError]` | | `shutdown()` | `None` | @@ -116,9 +116,20 @@ deviation=10, retry=None) -> Result[Trader, TradeError]` 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()` without arguments act on - the whole account**, including manual trades. A bot should always pass its - `magic` (and a symbol); an empty string `""` is rejected. +- **`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 diff --git a/docs/adr/0011-close-all-defaults-to-own-magic.md b/docs/adr/0011-close-all-defaults-to-own-magic.md new file mode 100644 index 0000000..c733061 --- /dev/null +++ b/docs/adr/0011-close-all-defaults-to-own-magic.md @@ -0,0 +1,66 @@ +# ADR 0011: Close-all and cancel-all default to the trader's own magic + +- Status: accepted (3.0.0). Decided by the package owner on 2026-11-09. + +## Context + +`close_positions()` and `cancel_pending_orders()` without a `magic` acted on +the whole account, manual trades and other bots included. The README warned +about it in bold, but a bot that forgets `magic` once closes everything. MT5 +gives trades opened by hand magic 0. + +## Decision + +- **Own by default.** Without `magic`, both calls act only on items whose + magic equals the trader's (`connect(..., magic=...)`). With a `symbol` + too: `close_positions("EURUSD")` closing someone's manual EURUSD trade is + the same hazard. This goes beyond the owner's question, which named only + the no-argument call. +- **The whole account is spelled `ANY_MAGIC`.** An explicit `magic=None` is + still "own". We chose a named value instead of `None` because a `None` read + from a missing config key would otherwise widen the call to the whole + account, the exact accident this change removes. +- **A `ticket` is closed whatever its magic.** The caller named the position. + Filtering it out would return `Ok([])` with the position still open. An + explicit `magic` still applies to a ticket. +- **Reads are unchanged.** `positions()` and `pending_orders()` still list + everything by default; they also accept `ANY_MAGIC`. A read cannot close + anything, and narrowing it would hide positions from a status screen. +- **A magic outside MT5's ulong is refused** as `INVALID_ARGUMENT` (`"42"`, + `True`, `1.5`, `-1`, `2**64`). `"42"` would match + nothing and report an empty success with every position still open. +- **The trader's own magic must be an integer from 0 to 2\*\*64-1** (MT5's + ulong). `connect()` returns `Err(INVALID_ARGUMENT)` and `Trader(...)` raises `ValueError` for + `None`, `ANY_MAGIC`, `"1001"` or `True`. Without this check, + `connect(magic=cfg.get("magic"))` with the key missing made "own" mean + "every magic" (found in review). +- **`Broker` keeps 2.x.** `Close(symbol)` and `CancelOrders(symbol)` closed + every magic in 2.x, so the facade passes `ANY_MAGIC`. + +## Consequences + +- A trader connected with the default `magic=0` shares that magic with manual + trades, so its close-all still closes them. The protection only works once + a bot sets its own `magic`. `connect()` keeps `magic=0` as its default + rather than making `magic` required; that is an API choice left to the + owner before release (`Broker` builds its `Trader` directly and is not + affected either way). A defaulted close/cancel on a magic-0 trader that + matches something logs a warning that manual trades are included; passing + `magic=0` explicitly acknowledges it. +- On a **netting** account one position per symbol collects every deal, and + it keeps the magic of the deal that opened it. A bot's deal that merges + into a manual position is then not "own", and a manual deal that merges + into the bot's position is. The magic filter cannot separate them; this is + 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 + 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 + `Trader`. +- `close_positions()` ported from 2.x `Close()` now leaves positions of other + magics open. MIGRATION.md maps `Close(s)` to + `close_positions(s, magic=ANY_MAGIC)` for an exact equivalent. +- The read/write asymmetry (`None` = all for reads, own for closes) is + deliberate. The parameter docstrings state it. diff --git a/src/PythonMetaTrader5/__init__.py b/src/PythonMetaTrader5/__init__.py index f133f6b..0070c72 100644 --- a/src/PythonMetaTrader5/__init__.py +++ b/src/PythonMetaTrader5/__init__.py @@ -18,6 +18,8 @@ from PythonMetaTrader5.connection import connect as connect from PythonMetaTrader5.domain.errors import ErrorKind as ErrorKind from PythonMetaTrader5.domain.errors import TradeError as TradeError +from PythonMetaTrader5.domain.inputs import ANY_MAGIC as ANY_MAGIC +from PythonMetaTrader5.domain.inputs import AnyMagic as AnyMagic from PythonMetaTrader5.domain.market import PendingKind as PendingKind from PythonMetaTrader5.domain.market import PendingOrder as PendingOrder from PythonMetaTrader5.domain.market import Position as Position @@ -33,6 +35,8 @@ from PythonMetaTrader5.result import Result as Result _OWN_NAMES = ( + "ANY_MAGIC", + "AnyMagic", "BatchFailure", "Broker", "Err", diff --git a/src/PythonMetaTrader5/application/batch.py b/src/PythonMetaTrader5/application/batch.py index 0fde847..3bc9e74 100644 --- a/src/PythonMetaTrader5/application/batch.py +++ b/src/PythonMetaTrader5/application/batch.py @@ -7,6 +7,7 @@ from typing import Protocol, TypeVar from PythonMetaTrader5.domain.errors import TradeError +from PythonMetaTrader5.domain.inputs import ANY_MAGIC, AnyMagic from PythonMetaTrader5.domain.market import TradeReceipt from PythonMetaTrader5.result import Err, Ok, Result @@ -53,5 +54,7 @@ def run_batch( return Ok(succeeded) -def with_magic(items: list[_T], magic: int | None) -> list[_T]: - return items if magic is None else [item for item in items if item.magic == magic] +def with_magic(items: list[_T], magic: int | AnyMagic | None) -> list[_T]: + if magic is None or magic is ANY_MAGIC: + return items + return [item for item in items if item.magic == magic] diff --git a/src/PythonMetaTrader5/application/magic_scope.py b/src/PythonMetaTrader5/application/magic_scope.py new file mode 100644 index 0000000..7f7e559 --- /dev/null +++ b/src/PythonMetaTrader5/application/magic_scope.py @@ -0,0 +1,65 @@ +"""Which magic a close-all / cancel-all acts on when the caller gives none (ADR 0011). + +Kept apart from Trader: the rule and the warnings it owes are one decision, +and they would otherwise push trader.py past the file-length limit. +""" + +from __future__ import annotations + +import logging +from collections.abc import Callable +from typing import TypeVar + +from PythonMetaTrader5.domain.errors import TradeError +from PythonMetaTrader5.domain.inputs import ANY_MAGIC, AnyMagic, magic_filter +from PythonMetaTrader5.result import Ok, Result + +log = logging.getLogger("PythonMetaTrader5") +_T = TypeVar("_T") + + +def resolve( + own: int, magic: int | AnyMagic | None, ticket: int | None +) -> Result[int | AnyMagic, TradeError]: + """The magic to filter by: the caller's, else the trader's own.""" + checked = magic_filter(magic) + if not isinstance(checked, Ok): + return checked + if checked.value is not None: + return Ok(checked.value) + # A named ticket is explicit intent: filtering it out by magic would + # report Ok([]) for a position the caller asked to close. + return Ok(ANY_MAGIC if ticket is not None else own) + + +def warn_about_default( + own: int, + magic: object, + ticket: int | None, + matched: list[_T], + everything: Callable[[], Result[list[_T], TradeError]], +) -> None: + """Say what the own-magic default cannot know; quiet once a magic is given.""" + if magic is not None or ticket is not None: + return + if matched: + if own == 0: + # magic 0 stays allowed (it is the connect() default), but then + # "own" includes every manual trade. + log.warning( + "trader magic is 0, which manual trades share: this close/cancel " + "includes them; set magic at connect(), or pass magic=0 to confirm" + ) + return + # Matched nothing: on netting the bot's deal may have merged into a position + # 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: + 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 " + "first magic); pass magic=ANY_MAGIC to include them", + own, + len(others.value), + ) diff --git a/src/PythonMetaTrader5/application/trader.py b/src/PythonMetaTrader5/application/trader.py index 2cd5add..37de59c 100644 --- a/src/PythonMetaTrader5/application/trader.py +++ b/src/PythonMetaTrader5/application/trader.py @@ -5,12 +5,20 @@ from dataclasses import replace from types import TracebackType +from PythonMetaTrader5.application import magic_scope from PythonMetaTrader5.application.batch import BatchFailure, run_batch, with_magic from PythonMetaTrader5.application.entries import StopInput, validate_entry from PythonMetaTrader5.application.execution import RetryPolicy, execute from PythonMetaTrader5.application.ports import Clock, Terminal from PythonMetaTrader5.domain.errors import TradeError -from PythonMetaTrader5.domain.inputs import symbol_filter, ticket_filter +from PythonMetaTrader5.domain.inputs import ( + ANY_MAGIC, + AnyMagic, + magic_filter, + own_magic, + symbol_filter, + ticket_filter, +) from PythonMetaTrader5.domain.market import PendingKind, PendingOrder, Position, TradeReceipt from PythonMetaTrader5.domain.orders import Side, validate_comment from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest @@ -30,7 +38,11 @@ def __init__( ) -> None: self._terminal = terminal self._clock = clock - self._magic = magic + own = own_magic(magic) + if isinstance(own, Err): + # A constructor cannot return a Result; connect() reports this as Err. + raise ValueError(own.error.message) + self._magic = own.value self._deviation = deviation self._retry = retry or RetryPolicy() @@ -115,20 +127,30 @@ def close_positions( symbol: str | None = None, *, ticket: int | None = None, - magic: int | None = None, + magic: int | AnyMagic | None = None, comment: str | None = None, ) -> Result[list[TradeReceipt], BatchFailure]: """Close matching positions; ``ticket`` takes precedence over ``symbol``. - With neither ``symbol``, ``ticket`` nor ``magic`` this closes EVERY position - on the account, manual ones included. Pass ``magic`` to touch only your own. + Only the trader's own ``magic`` unless another ``magic`` is given; + ``magic=ANY_MAGIC`` closes every position, manual ones included. A + ``ticket`` is closed whatever its magic. """ text = validate_comment(comment) if isinstance(text, Err): return Err(BatchFailure((), (text.error,))) - listed = self.positions(None if ticket is not None else symbol, ticket=ticket, magic=magic) + own = magic_scope.resolve(self._magic, magic, ticket) + if isinstance(own, Err): + return Err(BatchFailure((), (own.error,))) + listed = self.positions( + None if ticket is not None else symbol, ticket=ticket, magic=own.value + ) if isinstance(listed, Err): return Err(BatchFailure((), (listed.error,))) + scope = None if ticket is not None else symbol + magic_scope.warn_about_default( + self._magic, magic, ticket, listed.value, lambda: self.positions(scope, magic=ANY_MAGIC) + ) # One spec lookup per symbol, not per position: close-all is time-critical. specs: dict[str, Result[SymbolSpec, TradeError]] = {} @@ -143,39 +165,66 @@ def cancel_pending_orders( self, symbol: str | None = None, *, - magic: int | None = None, + magic: int | AnyMagic | None = None, kind: PendingKind | None = None, ) -> Result[list[TradeReceipt], BatchFailure]: - listed = self.pending_orders(symbol, magic=magic, kind=kind) + """Cancel matching pending orders of the trader's own ``magic`` by default. + + ``magic=ANY_MAGIC`` cancels every order on the account, manual ones included. + """ + own = magic_scope.resolve(self._magic, magic, None) + if isinstance(own, Err): + return Err(BatchFailure((), (own.error,))) + listed = self.pending_orders(symbol, magic=own.value, kind=kind) if isinstance(listed, Err): return Err(BatchFailure((), (listed.error,))) + magic_scope.warn_about_default( + self._magic, + magic, + None, + listed.value, + lambda: self.pending_orders(symbol, magic=ANY_MAGIC, kind=kind), + ) return run_batch(listed.value, self._cancel_one) # ----------------------------------------------------------------- queries def positions( - self, symbol: str | None = None, *, ticket: int | None = None, magic: int | None = None + self, + symbol: str | None = None, + *, + ticket: int | None = None, + magic: int | AnyMagic | None = None, ) -> Result[list[Position], TradeError]: + """Every position by default: a read never needs the own-magic guard.""" + checked = magic_filter(magic) + if isinstance(checked, Err): + return checked for check in (symbol_filter(symbol), ticket_filter(ticket)): if isinstance(check, Err): return check listed = self._terminal.positions(symbol=symbol, ticket=ticket) - return listed if isinstance(listed, Err) else Ok(with_magic(listed.value, magic)) + if isinstance(listed, Err): + return listed + return Ok(with_magic(listed.value, checked.value)) def pending_orders( self, symbol: str | None = None, *, - magic: int | None = None, + magic: int | AnyMagic | None = None, kind: PendingKind | None = None, ) -> Result[list[PendingOrder], TradeError]: - checked = symbol_filter(symbol) + checked = magic_filter(magic) if isinstance(checked, Err): return checked + symbol_checked = symbol_filter(symbol) + if isinstance(symbol_checked, Err): + return symbol_checked listed = self._terminal.pending_orders(symbol=symbol) if isinstance(listed, Err): return listed - orders = with_magic(listed.value, magic) + orders = with_magic(listed.value, checked.value) return Ok(orders if kind is None else [o for o in orders if o.kind is kind]) def shutdown(self) -> None: diff --git a/src/PythonMetaTrader5/connection.py b/src/PythonMetaTrader5/connection.py index f01cc8a..61dd53f 100644 --- a/src/PythonMetaTrader5/connection.py +++ b/src/PythonMetaTrader5/connection.py @@ -10,6 +10,7 @@ from PythonMetaTrader5.application.ports import Credentials, parse_login from PythonMetaTrader5.application.trader import Trader from PythonMetaTrader5.domain.errors import ErrorKind, TradeError +from PythonMetaTrader5.domain.inputs import own_magic from PythonMetaTrader5.result import Err, Ok, Result log = logging.getLogger("PythonMetaTrader5") @@ -34,6 +35,9 @@ def connect( ErrorKind.INVALID_ARGUMENT, f"login must be a positive integer, got {login!r}" ) ) + own = own_magic(magic) + if isinstance(own, Err): + return own loaded = MetaTrader5Terminal.load() if isinstance(loaded, Err): return loaded @@ -45,4 +49,4 @@ def connect( # Login and server only: account_info() also carries the owner's name and # balance, which do not belong in application logs. log.info("connected to %s as %s", server, account) - return Ok(Trader(terminal, SystemClock(), magic=magic, deviation=deviation, retry=retry)) + return Ok(Trader(terminal, SystemClock(), magic=own.value, deviation=deviation, retry=retry)) diff --git a/src/PythonMetaTrader5/domain/inputs.py b/src/PythonMetaTrader5/domain/inputs.py index 27533fc..258b4b9 100644 --- a/src/PythonMetaTrader5/domain/inputs.py +++ b/src/PythonMetaTrader5/domain/inputs.py @@ -9,7 +9,9 @@ from __future__ import annotations from dataclasses import replace +from enum import Enum from numbers import Integral +from typing import Final from PythonMetaTrader5.domain.amounts import positive_float from PythonMetaTrader5.domain.errors import ErrorKind, TradeError @@ -53,3 +55,52 @@ def symbol_filter(symbol: str | None) -> Result[str | None, TradeError]: if symbol == "": return Err(TradeError(ErrorKind.INVALID_ARGUMENT, "symbol must not be empty")) return Ok(symbol) + + +class AnyMagic(Enum): + """The type of ``ANY_MAGIC``.""" + + ANY = "any" + + +# A named value, not None: close-all and cancel-all default to the trader's own +# magic, and a None read from a missing config key must not widen them to the +# whole account (ADR 0011). +ANY_MAGIC: Final = AnyMagic.ANY +# MT5 stores magic as a ulong; a larger value would overflow in order_send. +_MAX_MAGIC: Final = 2**64 - 1 + + +def magic_filter(magic: object) -> Result[int | AnyMagic | None, TradeError]: + # "42" or True would match no position and report an empty success with + # everything still open. 0 is valid: it is what manual trades carry. + if magic is None or magic is ANY_MAGIC: + return Ok(magic) + if ( + isinstance(magic, bool) + or not isinstance(magic, Integral) + or not 0 <= int(magic) <= _MAX_MAGIC + ): + return Err( + TradeError( + ErrorKind.INVALID_ARGUMENT, + f"magic must be an integer from 0 to 2**64-1 or ANY_MAGIC, got {magic!r}", + ) + ) + return Ok(int(magic)) + + +def own_magic(magic: object) -> Result[int, TradeError]: + """The magic a trader stamps on its orders and closes by default.""" + checked = magic_filter(magic) + # None or ANY_MAGIC here would make the own-magic default mean "every magic", + # and a missing config key would close the whole account (ADR 0011). One + # message for every refusal: magic_filter's would suggest ANY_MAGIC. + if isinstance(checked, Err) or not isinstance(checked.value, int): + return Err( + TradeError( + ErrorKind.INVALID_ARGUMENT, + f"the trader's own magic must be an integer from 0 to 2**64-1, got {magic!r}", + ) + ) + return Ok(checked.value) diff --git a/src/PythonMetaTrader5/legacy/broker.py b/src/PythonMetaTrader5/legacy/broker.py index 3c04018..096363f 100644 --- a/src/PythonMetaTrader5/legacy/broker.py +++ b/src/PythonMetaTrader5/legacy/broker.py @@ -16,7 +16,7 @@ from PythonMetaTrader5.application.ports import Clock, Credentials, Terminal, parse_login from PythonMetaTrader5.application.trader import Trader from PythonMetaTrader5.domain.errors import ErrorKind, TradeError -from PythonMetaTrader5.domain.inputs import positive_number +from PythonMetaTrader5.domain.inputs import ANY_MAGIC, positive_number from PythonMetaTrader5.domain.market import PendingKind, TradeReceipt from PythonMetaTrader5.domain.orders import Side from PythonMetaTrader5.legacy import views @@ -194,7 +194,8 @@ def Close( # 2.x crashed here without closing anything; 3.x would close the account. log.error("%s: Close needs a symbol or ticket", self.log) return False - result = trader.close_positions(symbol, ticket=ticket, comment=comment) + # 2.x closed every magic; the 3.x own-magic default would skip them. + result = trader.close_positions(symbol, ticket=ticket, magic=ANY_MAGIC, comment=comment) if isinstance(result, Err): log.error("%s: closing %s: %s", self.log, symbol, result.error) return False @@ -211,7 +212,7 @@ def CancelOrders(self, symbol: str) -> None: log.error("%s: CancelOrders needs a symbol", self.log) return # 2.x only ever cancelled limit orders; stop orders stay untouched. - result = trader.cancel_pending_orders(symbol, kind=PendingKind.LIMIT) + result = trader.cancel_pending_orders(symbol, magic=ANY_MAGIC, kind=PendingKind.LIMIT) if isinstance(result, Err): log.error("%s: cancelling orders on %s: %s", self.log, symbol, result.error) diff --git a/tests/integration/test_demo_account.py b/tests/integration/test_demo_account.py index 166d439..fca790d 100644 --- a/tests/integration/test_demo_account.py +++ b/tests/integration/test_demo_account.py @@ -27,6 +27,9 @@ REQUIRED = ("MT5_LOGIN", "MT5_PASSWORD", "MT5_SERVER") # Distinct from any manual trading so cleanup never touches foreign positions. MAGIC = 930_117 +# Stands for another bot. Cleaned up before and after, so a killed run cannot +# break the next one. +FOREIGN_MAGIC = MAGIC + 1 SYMBOL = os.environ.get("MT5_SYMBOL", "EURUSD") @@ -47,8 +50,10 @@ def trader() -> Iterator[Trader]: if account is None or account.trade_mode != mt5.ACCOUNT_TRADE_MODE_DEMO: result.value.shutdown() pytest.fail("refusing to trade: the account is not a demo account") + result.value.close_positions(magic=FOREIGN_MAGIC) yield result.value result.value.close_positions(magic=MAGIC) + result.value.close_positions(magic=FOREIGN_MAGIC) result.value.cancel_pending_orders(magic=MAGIC) result.value.shutdown() @@ -134,3 +139,46 @@ def test_comment_limit_matches_the_installed_package( assert checked is None assert code == mt5.RES_E_INVALID_PARAMS, (code, message) assert "comment" in message, message + + +def test_close_all_leaves_another_magic_and_a_ticket_still_closes_it(trader: Trader) -> None: + # Opened past our library, as another bot or a manual trade would be. + if mt5.account_info().margin_mode != mt5.ACCOUNT_MARGIN_MODE_RETAIL_HEDGING: + # On netting the deal merges into an existing position and keeps its magic. + pytest.skip("needs a hedging account") + info = mt5.symbol_info(SYMBOL) + # Same order of preference as SymbolSpec.market_filling: FOK, IOC, RETURN. + filling = ( + mt5.ORDER_FILLING_FOK + if info.filling_mode & 1 + else mt5.ORDER_FILLING_IOC + if info.filling_mode & 2 + else mt5.ORDER_FILLING_RETURN + ) + sent = mt5.order_send( + { + "action": mt5.TRADE_ACTION_DEAL, + "symbol": SYMBOL, + "volume": info.volume_min, + "type": mt5.ORDER_TYPE_BUY, + "price": mt5.symbol_info_tick(SYMBOL).ask, + "deviation": 20, + "magic": FOREIGN_MAGIC, + "type_filling": filling, + "comment": "pmt5 foreign", + } + ) + if sent is not None and sent.retcode == mt5.TRADE_RETCODE_MARKET_CLOSED: + pytest.skip("market closed") + assert sent is not None, mt5.last_error() + assert sent.retcode == mt5.TRADE_RETCODE_DONE, sent + try: + assert isinstance(trader.close_positions(), Ok) + foreign = trader.positions(SYMBOL, magic=FOREIGN_MAGIC) + assert isinstance(foreign, Ok) + assert sent.order in [p.ticket for p in foreign.value] + finally: + closed = trader.close_positions(ticket=sent.order) + assert isinstance(closed, Ok), closed + assert len(closed.value) == 1 + assert trader.positions(SYMBOL, magic=FOREIGN_MAGIC) == Ok([]) diff --git a/tests/unit/test_failure_paths.py b/tests/unit/test_failure_paths.py index 7a3892b..541c5a3 100644 --- a/tests/unit/test_failure_paths.py +++ b/tests/unit/test_failure_paths.py @@ -11,7 +11,7 @@ def btc_position() -> Position: - return make_position(9, symbol="BTCUSD", price_open=1.0, price_current=1.0) + return make_position(9, symbol="BTCUSD", price_open=1.0, price_current=1.0, magic=42) @pytest.mark.parametrize("policy", [{"attempts": 0}, {"delay_seconds": -1.0}]) diff --git a/tests/unit/test_own_magic.py b/tests/unit/test_own_magic.py new file mode 100644 index 0000000..94b742e --- /dev/null +++ b/tests/unit/test_own_magic.py @@ -0,0 +1,274 @@ +"""Close-all / cancel-all touch only the trader's own magic unless told otherwise (ADR 0011).""" + +import logging +import sys + +import pytest + +from PythonMetaTrader5 import ( + ANY_MAGIC, + AnyMagic, + Broker, + ErrorKind, + PendingKind, + PendingOrder, + Side, + connect, +) +from PythonMetaTrader5.application.trader import Trader +from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest +from PythonMetaTrader5.result import Err, Ok + +from .fake_mt5 import FakeMT5 +from .fakes import FakeClock, FakeTerminal, make_position + +OWN = 42 # the conftest trader's magic +MANUAL = 0 # what MT5 stores for trades opened by hand + + +def closed_tickets(terminal: FakeTerminal) -> list[int | None]: + return [r.position for r in terminal.sent if isinstance(r, OrderRequest)] + + +def cancelled_tickets(terminal: FakeTerminal) -> list[int]: + return [r.order for r in terminal.sent if isinstance(r, CancelRequest)] + + +def order(ticket: int, magic: int) -> PendingOrder: + return PendingOrder( + ticket=ticket, + symbol="EURUSD", + side=Side.BUY, + kind=PendingKind.LIMIT, + volume=0.1, + price=1.0, + magic=magic, + comment="", + ) + + +@pytest.fixture +def mt5(monkeypatch: pytest.MonkeyPatch) -> FakeMT5: + fake = FakeMT5() + monkeypatch.setitem(sys.modules, "MetaTrader5", fake) + return fake + + +@pytest.fixture +def mixed_positions(terminal: FakeTerminal) -> FakeTerminal: + terminal.open_positions = [ + make_position(1, magic=OWN), + make_position(2, magic=MANUAL), + make_position(3, magic=7), + ] + return terminal + + +@pytest.mark.parametrize("call", [(), ("EURUSD",)]) +def test_close_without_magic_closes_only_own_positions( + trader: Trader, mixed_positions: FakeTerminal, call: tuple[str, ...] +) -> None: + assert isinstance(trader.close_positions(*call), Ok) + assert closed_tickets(mixed_positions) == [1] + + +def test_an_explicit_none_is_still_own_not_the_whole_account( + trader: Trader, mixed_positions: FakeTerminal +) -> None: + # A None read from a missing config key must not widen the blast radius. + trader.close_positions(magic=None) + assert closed_tickets(mixed_positions) == [1] + + +def test_any_magic_closes_the_whole_account(trader: Trader, mixed_positions: FakeTerminal) -> None: + trader.close_positions(magic=ANY_MAGIC) + assert closed_tickets(mixed_positions) == [1, 2, 3] + + +def test_an_explicit_magic_selects_that_magic( + trader: Trader, mixed_positions: FakeTerminal +) -> None: + trader.close_positions(magic=7) + assert closed_tickets(mixed_positions) == [3] + + +def test_a_ticket_is_closed_whatever_its_magic( + trader: Trader, mixed_positions: FakeTerminal +) -> None: + # Filtering it out would return Ok([]) for a position the caller named. + result = trader.close_positions(ticket=2) + assert isinstance(result, Ok) + assert closed_tickets(mixed_positions) == [2] + + +def test_cancel_without_magic_cancels_only_own_orders( + trader: Trader, terminal: FakeTerminal +) -> None: + terminal.open_orders = [order(5, OWN), order(6, MANUAL), order(7, 7)] + trader.cancel_pending_orders() + assert cancelled_tickets(terminal) == [5] + + +def test_cancel_with_any_magic_cancels_every_order(trader: Trader, terminal: FakeTerminal) -> None: + terminal.open_orders = [order(5, OWN), order(6, MANUAL), order(7, 7)] + trader.cancel_pending_orders(magic=ANY_MAGIC) + assert cancelled_tickets(terminal) == [5, 6, 7] + + +def test_queries_still_list_everything_by_default( + trader: Trader, mixed_positions: FakeTerminal +) -> None: + listed = trader.positions() + assert isinstance(listed, Ok) + assert [p.ticket for p in listed.value] == [1, 2, 3] + assert trader.positions(magic=ANY_MAGIC) == listed + + +@pytest.mark.parametrize("magic", ["42", True, 1.5, -1, 2**64]) +def test_a_magic_that_is_not_a_magic_number_is_refused( + trader: Trader, mixed_positions: FakeTerminal, magic: object +) -> None: + # "42" != 42 would match nothing and report Ok([]) with every position open. + closed = trader.close_positions(magic=magic) # type: ignore[arg-type] + assert isinstance(closed, Err) + assert closed.error.errors[0].kind is ErrorKind.INVALID_ARGUMENT + cancelled = trader.cancel_pending_orders(magic=magic) # type: ignore[arg-type] + assert isinstance(cancelled, Err) + for listed in ( + trader.positions(magic=magic), # type: ignore[arg-type] + trader.pending_orders(magic=magic), # type: ignore[arg-type] + ): + assert isinstance(listed, Err) + assert listed.error.kind is ErrorKind.INVALID_ARGUMENT + assert mixed_positions.sent == [] + + +def test_legacy_close_and_cancel_keep_acting_on_every_magic( + terminal: FakeTerminal, clock: FakeClock +) -> None: + # 2.x Close(symbol) / CancelOrders(symbol) ignored magic numbers. + terminal.open_positions = [make_position(1, magic=7), make_position(2, magic=MANUAL)] + terminal.open_orders = [order(5, 7)] + with pytest.warns(DeprecationWarning, match="Broker is deprecated"): + broker = Broker(123, "pw", "Demo", terminal=terminal, clock=clock) + assert broker.Close("EURUSD") is True + broker.CancelOrders("EURUSD") + assert closed_tickets(terminal) == [1, 2] + assert cancelled_tickets(terminal) == [5] + + +@pytest.mark.parametrize("magic", [None, ANY_MAGIC, "1001", True, -1, 2**64]) +def test_connect_refuses_an_own_magic_that_is_not_a_magic_number( + mt5: FakeMT5, magic: object +) -> None: + # magic=None from a missing config key made the "own" default mean "all". + result = connect(123, "pw", "Demo", magic=magic) # type: ignore[arg-type] + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_ARGUMENT + assert mt5.calls == [] + + +@pytest.mark.parametrize("magic", [None, ANY_MAGIC, "1001", True, -1, 2**64]) +def test_trader_refuses_an_own_magic_that_is_not_a_magic_number( + terminal: FakeTerminal, clock: FakeClock, magic: object +) -> None: + with pytest.raises(ValueError, match="magic"): + Trader(terminal, clock, magic=magic) # type: ignore[arg-type] + + +def test_close_all_with_own_magic_zero_warns_that_it_includes_manual_trades( + terminal: FakeTerminal, clock: FakeClock, caplog: pytest.LogCaptureFixture +) -> None: + terminal.open_positions = [make_position(1, magic=MANUAL)] + terminal.open_orders = [order(5, MANUAL)] + trader = Trader(terminal, clock) + with caplog.at_level(logging.WARNING, logger="PythonMetaTrader5"): + trader.close_positions() + trader.cancel_pending_orders() + warnings = [r.getMessage() for r in caplog.records if "manual trades" in r.getMessage()] + assert len(warnings) == 2 + # ANY_MAGIC would widen the call; an explicit 0 is the way to acknowledge it. + assert all("magic=0" in w and "ANY_MAGIC" not in w for w in warnings) + + +def test_magic_zero_warning_only_when_something_is_actually_affected( + terminal: FakeTerminal, clock: FakeClock, caplog: pytest.LogCaptureFixture +) -> None: + trader = Trader(terminal, clock) + with caplog.at_level(logging.WARNING, logger="PythonMetaTrader5"): + trader.close_positions() # nothing open + trader.close_positions("") # refused before anything is listed + terminal.open_positions = [make_position(1, magic=MANUAL)] + trader.close_positions(magic=0) # acknowledged explicitly + assert not [r for r in caplog.records if "manual trades" in r.getMessage()] + + +def test_no_warning_once_the_trader_has_its_own_magic_or_asks_for_all( + trader: Trader, mixed_positions: FakeTerminal, caplog: pytest.LogCaptureFixture +) -> None: + with caplog.at_level(logging.WARNING, logger="PythonMetaTrader5"): + trader.close_positions() + Trader(mixed_positions, FakeClock()).close_positions(magic=ANY_MAGIC) + assert not [r for r in caplog.records if "manual trades" in r.getMessage()] + + +def test_any_magic_type_is_public_for_annotations() -> None: + assert type(ANY_MAGIC) is AnyMagic + + +def test_the_largest_mt5_magic_is_accepted(terminal: FakeTerminal, clock: FakeClock) -> None: + # MT5 stores magic as a ulong; anything above would overflow in order_send. + largest = 2**64 - 1 + terminal.open_positions = [make_position(1, magic=largest)] + trader = Trader(terminal, clock, magic=largest) + assert isinstance(trader.close_positions(), Ok) + assert closed_tickets(terminal) == [1] + + +def test_a_default_close_that_matches_nothing_says_what_it_left_open( + trader: Trader, terminal: FakeTerminal, caplog: pytest.LogCaptureFixture +) -> None: + # Netting: the bot's deal merged into a manual position, which kept magic 0. + terminal.open_positions = [make_position(1, magic=MANUAL)] + with caplog.at_level(logging.WARNING, logger="PythonMetaTrader5"): + assert trader.close_positions("EURUSD") == Ok([]) + terminal.open_orders = [order(5, MANUAL)] + assert trader.cancel_pending_orders("EURUSD") == Ok([]) + left = [r.getMessage() for r in caplog.records if "left open" in r.getMessage()] + assert len(left) == 2 + assert all("ANY_MAGIC" in m for m in left) + assert terminal.sent == [] + + +def test_no_left_open_warning_when_own_items_were_handled( + trader: Trader, mixed_positions: FakeTerminal, caplog: pytest.LogCaptureFixture +) -> None: + with caplog.at_level(logging.WARNING, logger="PythonMetaTrader5"): + trader.close_positions("EURUSD") + trader.close_positions(magic=7) + assert not [r for r in caplog.records if "left open" in r.getMessage()] + + +@pytest.mark.parametrize("magic", ["1001", True, -1, 2**64, None, ANY_MAGIC]) +def test_own_magic_error_does_not_suggest_any_magic(mt5: FakeMT5, magic: object) -> None: + result = connect(123, "pw", "Demo", magic=magic) # type: ignore[arg-type] + assert isinstance(result, Err) + assert "ANY_MAGIC" not in result.error.message + + +def test_cancel_with_any_magic_still_keeps_to_the_symbol( + trader: Trader, terminal: FakeTerminal +) -> None: + xau = PendingOrder( + ticket=8, + symbol="XAUUSD", + side=Side.BUY, + kind=PendingKind.LIMIT, + volume=0.1, + price=1.0, + magic=7, + comment="", + ) + terminal.open_orders = [order(5, OWN), order(6, MANUAL), xau] + trader.cancel_pending_orders("EURUSD", magic=ANY_MAGIC) + assert cancelled_tickets(terminal) == [5, 6] diff --git a/tests/unit/test_pending_orders.py b/tests/unit/test_pending_orders.py index 03c9cb5..283624e 100644 --- a/tests/unit/test_pending_orders.py +++ b/tests/unit/test_pending_orders.py @@ -40,13 +40,14 @@ def order(ticket: int, symbol: str, magic: int = 42) -> PendingOrder: ) -def test_cancel_removes_every_pending_order_of_the_symbol( +def test_cancel_removes_the_traders_own_pending_orders_of_the_symbol( trader: Trader, terminal: FakeTerminal ) -> None: terminal.open_orders = [order(5, "EURUSD"), order(6, "XAUUSD"), order(7, "EURUSD", magic=1)] result = trader.cancel_pending_orders("EURUSD") assert isinstance(result, Ok) - assert terminal.sent == [CancelRequest(order=5), CancelRequest(order=7)] + # Order 7 has another magic; the own-magic default leaves it (ADR 0011). + assert terminal.sent == [CancelRequest(order=5)] def test_cancel_with_magic_filter(trader: Trader, terminal: FakeTerminal) -> None: diff --git a/tests/unit/test_safety_edges.py b/tests/unit/test_safety_edges.py index 6702d63..bb2c69f 100644 --- a/tests/unit/test_safety_edges.py +++ b/tests/unit/test_safety_edges.py @@ -21,7 +21,7 @@ def position(ticket: int, volume: float = 0.5) -> Position: - return make_position(ticket, volume=volume, price_open=1.0, price_current=1.0) + return make_position(ticket, volume=volume, price_open=1.0, price_current=1.0, magic=42) def test_empty_symbol_is_rejected_instead_of_meaning_all( diff --git a/tests/unit/test_symbol_data.py b/tests/unit/test_symbol_data.py index 995839c..0a608c9 100644 --- a/tests/unit/test_symbol_data.py +++ b/tests/unit/test_symbol_data.py @@ -86,7 +86,7 @@ def test_a_position_on_a_symbol_with_broken_data_can_still_be_closed( trader: Trader, terminal: FakeTerminal, broken: dict[str, float] ) -> None: terminal.specs["EURUSD"] = replace(EURUSD, **broken) - terminal.open_positions = [make_position(1)] + terminal.open_positions = [make_position(1, magic=42)] closed = trader.close_positions("EURUSD") assert isinstance(closed, Ok) assert len(closed.value) == 1