Skip to content

v3.0.0: typed, safe rewrite with 2.x compatibility facade - #14

Merged
Akinzou merged 28 commits into
masterfrom
rewrite/v3
Nov 9, 2026
Merged

Akinzou merged 28 commits into
masterfrom
rewrite/v3

Conversation

@Akinzou

@Akinzou Akinzou commented Nov 9, 2026 •

Copy link
Copy Markdown
Owner

Goal

Turn PythonMetaTrader5 into a typed, tested library whose trading calls never block forever, never retry blindly and never fail silently, while existing 2.x scripts keep running through a deprecated Broker facade.

What changed

  • Architecture: Clean Architecture with Ports & Adapters. There are exactly two ports, one per process boundary (Terminal, Clock). Result (Ok/Err) is used at every boundary. See docs/architecture.md and docs/adr/0001–0010.
  • 2.x star import kept (ADR 0010): from PythonMetaTrader5 import * still brings in the MetaTrader5 namespace (symbol_info, ORDER_TYPE_BUY, ...), as the 2.x README relied on.
    • It is resolved lazily, so importing the library no longer imports MT5.
    • Re-exported functions hold the session lock (per call).
    • Our names win a collision (Tick).
    • A broken MT5 install keeps the import working, warns, and makes connect() return Err.
    • Debt: no caching of resolved names; on a broken install hasattr / getattr(.., None) give False without a warning.
    • The last commit (ceb1102: message prefix, warning stacklevel, CHANGELOG caveat) had no separate review round.
  • New API: connect() → Trader with open_position, place_limit_order, close_positions, cancel_pending_orders, positions and pending_orders. It adds magic numbers, Stop.points(), Stop.parse() and typed ErrorKinds.
  • 2.x compatibility: Broker keeps the same names and arguments. It returns LegacyPosition / LegacyReceipt named tuples with MT5's field names and field order, and emits a DeprecationWarning.
  • Safety (vs 2.x):
    • No endless retry loops; timeouts and lost connections are never retried.
    • A market deal counts as success only on DONE.
    • No Ctrl+E keystrokes.
    • Nothing that MT5 would misread is sent (ADR 0008): sl=0 ("no stop"), ticket=0, volume=True, NaN or infinite numbers, prices that snap to 0, an empty symbol.
    • Broken symbol data is refused on entries as BROKEN_SYMBOL_DATA; closes still work on such symbols.
    • MT5 calls are serialized by one process-wide lock (ADR 0009).
  • Packaging:
    • Python 3.10+.
    • CC-BY-NC-4.0 license metadata.
    • MetaTrader5 is installed only on Windows.
    • Dropped pyautogui and loguru.
    • Ships py.typed.
  • CI:
    • ruff and mypy --strict;
    • unit tests on 3.10–3.14;
    • a Windows job that runs tests/contract against the real MetaTrader5 wheel (constant values, result field names);
    • Semgrep;
    • the 300-line limit;
    • build and twine check.

Every behaviour change for users is listed in MIGRATION.md.

Review history (honest account)

  • After four /code-review high rounds, three independent reviews (trading correctness, 2.x compatibility, docs/tests honesty) still found real defects:

    • sl=0 opened an unprotected position and reported Ok;
    • ticket=0 reached positions_get (possibly "no filter" → close everything);
    • positions(symbol, ticket=) ignored the symbol;
    • a last_error() race could label a lost order "never sent";
    • legacy objects lacked MT5 fields;
    • CHANGELOG/MIGRATION had stale or wrong claims;
    • the Windows CI job did not test what it claimed.

    Fixed in 55be3e2, eeaee6b, 56457bc and 4546b05.

  • Eight more /code-review high rounds on those fixes followed (23f78ff … 880ca9c). a0f2aba introduced a regression: an invariant on SymbolSpec made positions on symbols with broken data impossible to close. Round 6 caught it, and 098ac0a reverted it before any push. Each fix commit lists its RED evidence.

Verification (local)

  • 300 tests pass (unit and contract, the contract ones against MetaTrader5 5.0.6231), 99% branch coverage.
  • 3 integration tests are skipped: they need a demo account.
  • ruff, ruff format, mypy --strict, the file-length check, python -m build and twine check --strict are clean.

Needs demo-account verification (pytest -m integration)

  • The filling mode for limit orders on market-execution brokers.
  • The terminal's 31-character comment limit.
  • positions_get / orders_get returning None vs ().

Known residual risks (conscious debt)

  • PLACED on exchange symbols: a market order may be acknowledged as PLACED and filled asynchronously. It is reported as OUTCOME_UNKNOWN: safe but noisy.
  • RETURN partial fills: the remainder of a partial fill can keep working, and nothing tracks it.
  • Truthiness in Broker: if broker.Buy(...) stays truthy for a partial or queued fill, as in 2.x. MIGRATION says to check retcode.
  • Close-all without a quote waits (attempts-1) × delay per position before NO_PRICE.
  • One-sided quote: a quote with bid or ask at 0 is NO_PRICE, even for a close that needs only the other side. This fails safe.
  • close_positions() / cancel_pending_orders() without arguments act on the whole account (documented in bold). Decision to confirm: should they default to the trader's own magic?
  • From round 8, not fixed (none sends an order, blocks a close, raises out of a Result or regresses this branch):
    • On a symbol whose point is unusable but whose tick size is valid, a points stop is only refused after the tick fetch. A symbol without quotes therefore reports NO_PRICE first.
    • digits coarser than the tick size (digits=1, tick 0.25) rounds levels off the grid. The server rejects them (10015/10016) instead of us.
    • Tradability is re-checked in price_on_grid and validate_volume for direct callers: duplicated work, one rule.
  • Legacy BuyLimit / SellLimit compare the raw level with the quote, as 2.x did. A level that snaps onto the quote is placed as a limit, not filled at market.

Semgrep findings

  • ERROR (high/critical): 0 at 16cc80b. This push is re-checked by CI.
  • MEDIUM: 2 github-actions-mutable-action-tag in python-publish.yml, fixed in 16cc80b.

Not done here

  • Nothing is published to PyPI.
  • Merging needs the owner: branch protection requires one approving review, and the author cannot approve their own PR.

Goal (v3 rewrite): turn PythonMetaTrader5 into a typed, tested library whose
trading calls never block forever, with a 2.x compatibility facade.

- Stop tracking the generated egg-info directory and add a .gitignore.
- Declare the real license (CC-BY-NC-4.0, SPDX) instead of the contradictory
  MIT classifier, and ship a LICENSE file.
- Mark the MetaTrader5 dependency win32-only: the official package has Windows
  wheels only, so an unconditional dependency breaks Linux CI and type checking.
- Raise the floor to Python 3.10 (match statements, PEP 604 unions); 3.6-3.9 are
  end-of-life.
- Configure pytest, coverage, ruff and mypy --strict.
Replaces the 2.x single-file Broker (its behaviour returns as a compatibility
facade in a later commit). The domain has no I/O and never imports MetaTrader5.

- Result (Ok/Err) for every expected failure at boundaries.
- SymbolSpec: price normalisation on the tick grid, not only to `digits`
  (index CFDs with tick 0.25 were rejected by 2.x), volume min/max/step
  validation, filling-mode choice from the symbol's flags.
- Stop: SL/TP as a price or as a distance in points (2.x semantics kept).
- Retcode classification. Retry only codes where the server provably did not
  execute; TIMEOUT/CONNECTION are not retried because the order may already be
  live and a retry would open a duplicate position.
- Comments over 31 characters are rejected instead of silently truncated.
Ports exist only for the two process boundaries: the MT5 terminal and time.

- open_position: SL/TP as prices (floats) or Stop.points distances, requotes
  retried with a fresh quote at most RetryPolicy.attempts times. 2.x looped
  forever on any unknown retcode (e.g. NO_MONEY), sending an order every 0.5 s.
- place_limit_order: RETURN filling, success on PLACED (10008).
- close_positions: closes each position on its own symbol. 2.x priced every
  close with the `symbol` argument, so close-by-ticket with symbol=None crashed.
- Batch operations return BatchFailure listing what succeeded and what failed,
  instead of a boolean that hid partial closes.
- magic filters for close/cancel/queries so a bot never touches manual trades.
- MetaTrader5Terminal is the only module that knows MT5 request dicts and
  numeric order types. It imports the package lazily, so the library (and
  its unit tests) import on Linux where MetaTrader5 has no wheels.
- Hidden symbols are selected into Market Watch automatically; a quote with
  a zero side is refused instead of trading at price 0.
- None from positions_get/orders_get is split into "empty" vs "failed" via
  last_error(); 2.x treated a broken IPC link as "no positions".
- connect() is the composition root and logs login@server only; 2.x logged
  the whole account_info (owner name, balance).
- Broker keeps 2.x names, arguments and return shapes and emits a
  DeprecationWarning. It no longer loops forever and no longer presses
  Ctrl+E: that hotkey toggles (not enables) Algo Trading and is typed into
  whichever window has focus.
- Logging uses stdlib `logging` without a NullHandler: with a NullHandler an
  unconfigured script would silently swallow every ERROR record, whereas
  stdlib's last-resort handler still prints them to stderr.
- .gitattributes normalises line endings to LF.
- Unit tests, ruff and mypy --strict on Python 3.10-3.14 (Linux).
- A Windows job installs the real MetaTrader5 wheel and builds the adapter
  against it, so a renamed constant fails CI instead of a live order.
- Semgrep: ERROR (high/critical) findings block the merge; WARNING (medium)
  findings are listed for the PR description.
- scripts/check_file_length.py enforces the 300-line limit on tracked files.
- Package build + twine check --strict.
- Actions pinned to commit SHAs so a moved tag cannot inject code.
- Integration tests run only with MT5_* credentials and refuse to trade on a
  non-demo account; they use a dedicated magic number for cleanup.
…d ADRs

ADRs record each decision as 'A over B because B silently breaks C':
ports per process boundary, Result at boundaries, bounded retries with no
retry on unknown outcome, no GUI automation, stdlib logging without a
NullHandler, the 2.x facade, filling mode and tick-grid pricing.
All found by /code-review high on this branch, each reproduced by a failing
test first (tests/unit/test_safety_edges.py).

- An empty symbol is rejected: MT5 treats a falsy filter as all symbols, so
  close_positions("") would have closed the whole account. The adapter now
  forwards "" as a filter instead of dropping it.
- Broker.Close(None) without a ticket closes nothing, as 2.x did.
- order_send returning None is OUTCOME_UNKNOWN unless last_error proves the
  request never left the process; a plain TERMINAL_ERROR invited a re-send.
- symbol_select failure is an error; a missing first quote is retried since
  nothing was sent yet.
- DONE_PARTIAL on a close is a PARTIAL_FILL error.
- Pending orders use the symbol filling mode: a fixed RETURN is refused by
  market-execution brokers, where the 2.x IOC was accepted.
- connect() maps any unusable login to INVALID_ARGUMENT and shuts the
  terminal down after a failed login.
- close-all reads each symbol spec once; closes use Tick.exit_price.
- SymbolSpec.stops_level removed: unused, and a local check would be wrong
  for brokers with floating stop levels (stops_level 0).
The Windows CI job builds the adapter against the real MetaTrader5 wheel; with
constants resolved lazily in _payload/_position a renamed TRADE_ACTION_* or
ORDER_TIME_GTC would only fail on the first live order.

Also states in the README and docstring that close_positions() and
cancel_pending_orders() without arguments act on the whole account.
Each finding reproduced by a failing test first (test_safety_edges.py).

- Pending orders on exchange-execution symbols use RETURN, the only mode that
  lets a limit rest in the book; elsewhere the symbol market rule stays.
- A close counts as done only on DONE; PLACED is OUTCOME_UNKNOWN and
  DONE_PARTIAL is PARTIAL_FILL.
- The adapter shuts the half-open session down after a failed login, so the
  Broker.login(ToEffect=True) loop can recover; connect() no longer does it.
- Broker.CancelOrders(None) cancels nothing, as 2.x did.
- Logins that int() would silently coerce (True, 12345678.9, negatives) are
  rejected instead of logging into another account.
- RES_E_* codes come from the MetaTrader5 module and last_error() is read
  once per failure.
- Unit tests patch MetaTrader5 with a fake (autouse): a new test reached the
  real initialize() and hung until timeout.
- README: one connection per process (the package is a global singleton).

Field removal check required by project rules for SymbolSpec.stops_level
(removed in a5a03d4), grep over the whole repo:
  $ grep -rn stops_level --include=*.py --include=*.md --include=*.toml .
  src/PythonMetaTrader5/domain/retcodes.py:39  (10016 message) -> reworded
  tests/unit/fake_mt5.py:99  (fake trade_stops_level)          -> removed
  after this commit: no references left. No DB, FKs, triggers or views exist.
…sions

Third review round; each finding reproduced by a failing test first
(tests/unit/test_confirmation.py).

- execute() confirms every market deal (entry and close) only on DONE.
  DONE_PARTIAL is PARTIAL_FILL and PLACED is OUTCOME_UNKNOWN, both with the
  receipt and never re-sent. The close-only special case is gone. Returning
  Ok for a partial entry let a bot believe it held 1 lot while holding 0.3.
- parse_login() is shared by connect() and Broker: ASCII digits or an
  int-like value via operator.index, so numpy ints still work while True,
  floats and non-ASCII digits (int("١") == 1) are rejected.
- A failed re-login no longer shuts down a session this adapter opened; MT5
  keeps one session per process, so that killed a working connection.
- SymbolSpec.exchange_execution is required: a default would quietly treat an
  exchange symbol as market execution. Adapter mapping now has a test.
- RES_S_OK read from the module; last_error() formatted in one place.
- README, MIGRATION, CHANGELOG and ADR 0003/0007 updated to the new rules.
Fourth review round. The previous commit kept a "live" session after a failed
re-login using a per-adapter flag. That was wrong: MT5 has one session per
process and connect() builds a new adapter each time, so the flag protected
nothing, and it stopped login(ToEffect=True) from ever recovering because the
half-open session was never released. Reproduced by failing tests first.

- The adapter always calls shutdown() after a failed initialize(); Broker
  marks itself disconnected so nothing trades on a released session.
- Credentials validates the login itself, so no construction path can hand
  MT5 True or a float.
- PARTIAL_FILL names the requested size and warns that with RETURN filling
  the remainder may still be working.
- A detached comment about RES_S_OK moved next to the code it explains.
Semgrep MEDIUM (github-actions-mutable-action-tag) x2 in python-publish.yml.
Pinned to the SHAs the v4/v5 tags point at today, so publishing behaves
exactly as before while a re-pointed tag can no longer inject code into the
job that holds the PyPI token.
… MT5 calls

Found by three independent reviews after the fourth /code-review round.

- sl=0 / tp=0 (or a price that snaps to 0.0, or a points distance that
  goes below zero) is INVALID_STOPS. MT5 reads 0.0 as "no stop", so a
  webhook with a missing SL field opened an unprotected position and
  reported Ok.
- A ticket that is not a positive integer (0, -5, True, 1.0, "7") is
  INVALID_ARGUMENT before positions_get is called; positions_get(ticket=0)
  may mean "no filter", which would close the whole account.
- Volume and prices must be positive finite numbers (numbers.Real, not
  bool): NaN/inf raised ValueError/OverflowError instead of returning Err,
  and volume=True traded one lot. volume_step <= 0 is an Err, not a
  ZeroDivisionError.
- The adapter applies symbol and ticket together; MT5 drops `symbol` once
  `ticket` is given, so positions("EURUSD", ticket=t) could return a
  position on another symbol.
- Every adapter call holds a module-level RLock, so an MT5 call and the
  last_error() read that explains it cannot interleave with another
  thread. A per-adapter lock instead of a module lock: rejected, because
  connect() builds a new adapter per call and two Traders share the one
  process-global session, so per-adapter locks protect nothing.

Splits (300-line limit, each one concern):
- domain/inputs.py: input rules with no I/O; plain functions, not a port.
- application/entries.py: Entry and validate_entry, the one place raw entry
  input becomes a request; Entry.request is an entity method instead of a
  Trader helper because it needs only the entry's own data.
- adapters/mt5_mapping.py: pure MT5-object -> domain mapping.

Removed/renamed private helpers; grep over src tests docs scripts *.md
.github for _reject_empty|_as_stop|_order_type_table|_validate_entry|
_entry_request|\._position\(|_Entry\b: no matches outside stale __pycache__.

RED: 36 of 40 new cases failed (4 of the volume cases already passed: 0, -0.1 and -inf are caught by the range check, and None by float() raising), the resolve-to-zero cases failed with
the guard disabled, and the lock test failed before the lock existed.
…eric strings

The 2.x Broker returned raw MetaTrader5 objects. MIGRATION promised "same
fields", but scripts using the missing ones broke, and no test noticed.

- GetPositions(): LegacyPosition now has every TradePosition field in
  MT5's order (swap, identifier, reason, time_msc, time_update,
  time_update_msc, external_id were missing; p[1] was symbol instead of
  time). as_dict=True keeps exactly the 12 keys 2.x built.
- Entries return LegacyReceipt, shaped like OrderSendResult: it gains
  retcode_external, indexing and _asdict(). `request` is always None
  because 3.x does not keep the echoed request.
- Volume, price, sl, tp and stoplimit given as strings are converted with
  float(), as 2.x did; garbage raises ValueError as in 2.x. Only strings
  are converted: float(True) would trade a stray bool as one lot. This
  also fixes a regression from 55be3e2, where Buy("EURUSD", "0.1") was
  refused.
- GetPositions(symbol, ticket=) selects by ticket alone, as in 2.x.

Position gains the extra fields in the domain rather than the legacy
layer keeping raw MT5 objects, which would bring MT5 types back into the
facade the port exists to isolate. TradeReceipt gains retcode_external.
Test helpers that built Position by hand now share fakes.make_position.

Split: legacy/arguments.py takes the pure 2.x argument rules out of
broker.py (300-line limit). Moved private names _legacy_stop and
_no_ticket: grep over src tests docs scripts *.md .github finds no
remaining use.

RED: all 7 tests in test_legacy_compat.py failed before the change.
…tries

The docs/tests review found test gaps that hid or could hide real bugs:

- tests/contract checks FakeMT5 constants, the fake result rows and the
  legacy NamedTuples against the installed MetaTrader5 package (values,
  field names and order). They sit outside tests/unit because the autouse
  fixture there swaps the module for FakeMT5. The Windows CI job ran the
  same faked unit tests as Ubuntu; it now runs these against the real wheel.
  Shown to fail by setting ORDER_FILLING_RETURN to 3 in the fake.
- login(ToEffect=True) never looped in any test (FakeTerminal could not
  fail N times, then succeed); it now has connect_failures and a test.
- Broker without an injected terminal (the production path) is covered.
- Weak asserts tightened:
  - The password check used the one-letter password "p".
  - A positions() magic filter was checked on an empty list.
  - CancelOrders() "is None" was always true.
  - A test name claimed a recovery the fake cannot model.
- The ci.yml comment on the Windows job now says what it proves.
…R 0008-0009

Docs fixes found by the independent reviews:

- CHANGELOG said a failed re-login keeps a working session. bc237d4
  reversed that, and the entry was never updated.
- MIGRATION said invalid input returns "the receipt". It returns None,
  because nothing was sent.
- MIGRATION said GetPositions has "the same fields". It now does, and the
  entry says so precisely.
- The MIGRATION example `[p.to_dict() for p in trader.positions().value]`
  raised on Err. It now matches on Ok/Err and notes `side` vs `type`.
- README said BatchFailure.succeeded shows "exactly which tickets closed".
  The receipts carry deal/order IDs, not position tickets.
- README and ADR 0003 said "every call returns". Broker.login(ToEffect=True)
  loops by design, and batches take the time limit per position.
- architecture.md said legacy works "through Trader and ports". It builds
  the default adapters itself.

MIGRATION gains the behaviour changes that were missing:
- failed logins disable the Broker, and one shared session per process;
- invalid input is refused before sending;
- sl=0 and unknown sl_type (2.x opened with no SL and no TP);
- volume=True;
- offset stops with an explicit price, including the market-execution case;
- Close() no longer loops, so a Close-then-Buy reversal must check the
  result;
- ticket=0;
- receipt and position shapes;
- the time/logger/pyautogui star exports;
- DeprecationWarning under -W error;
- limit-order filling.

ADR 0008 records why such inputs are refused. ADR 0009 records why the
terminal lock is per process, not per adapter.
…ecimal

- Legacy BuyLimit/SellLimit compared the raw stoplimit with the quote
  before any check. SellLimit(s, v, 0) "crossed" and was sent as a market
  SELL, and inf or True did the same. The level is now checked first.
- Stop.at_price()/points() ran float() on their argument, so True became
  1.0 before stop_input could refuse it. Broker(..., sl=True) opened with
  sl=1.0. The factories now store the value unconverted, stop_input checks
  it and rebuilds the Stop from the checked float, and the sign of a points
  distance is dropped in Stop._resolve.
- Decimal volumes and prices were refused because Decimal is not a
  numbers.Real. They worked before via float(), so this was a regression
  from 55be3e2. Decimal is now accepted explicitly.
- A bad price was checked after the symbol lookup. That cost a terminal
  round trip and could add the symbol to Market Watch. It is now checked
  first.
- as_dict builds the 2.x dict straight from Position. _V2_DICT_KEYS is
  removed; grep over src tests docs finds no other use.
- A test-fake comment now states the decision, not the action.

Not changed: number() conversion stays at the two legacy entry points
(OpenPosition, _limit). Every legacy entry method goes through one of them,
so a separate normaliser would be a third place to keep in sync.

RED: 7 of the 8 new cases failed before the change. The legacy limit at
NaN already returned None, because comparisons with NaN are false.
… validate_entry

Second /code-review high round, on 23f78ff, which went the wrong way:

- Stop stored raw values and left the checks to stop_input. That made it an
  anemic value object (the project rules forbid that), and two stops with
  the same meaning stopped being equal: Stop.points(-1000) !=
  Stop.points(1000). Stop.points(Decimal(...)).stop_loss() also raised
  TypeError. Stop now enforces positive-finite-float in __post_init__ and
  drops a distance's sign there, so the sign rule lives in one place
  instead of two. It raises ValueError, because a zero Stop cannot exist.
  Plain floats passed as sl/tp still come back as Err(INVALID_STOPS) from
  stop_input, without raising.
- Decimal("sNaN") raised ValueError / InvalidOperation out of the
  Result boundary. domain/amounts.positive_float is the single rule, used
  by both Stop and positive_number, and checks Decimal NaN before float().
  It is a plain function because it is pure: no port, no use case.
- "Check the price before the symbol lookup" was a convention each caller
  had to remember. The price is now validated inside validate_entry, after
  side/comment/stops, so a bad side is still the first error reported.
  Entry carries the price on the tick grid.
- as_dict is again a projection of as_object() (_V2_DICT_KEYS restored).
  The previous round's hand-written dict was a second mapping that could
  drift. Correctness wins over one allocation per row.
- Tests: the bool-stop test no longer runs its Trader loop once per
  sl_type for nothing. The bad-price test asserts INVALID_PRICE. Error
  precedence is pinned.

Not changed:
- The legacy crossing test still compares the raw level with the quote,
  as 2.x did (BuyLimit: `info.ask <= float(stoplimit)`).
- The legacy level check is repeated inside place_limit_order. The
  first check must run before the crossing test, and the second protects
  the 3.x API.

RED: against 23f78ff's src, 20 of the new or changed cases failed
(sNaN raising, Stop equality and Decimal, the Entry price field).
…r rule

Third /code-review high round, on 2359877:

- An explicit price that snaps to 0.0 on the tick grid (price=1e-6 on a
  5-digit symbol) was sent. A deal at price 0 fills at the market, which
  silently drops the caller's price. validate_entry now refuses it with
  INVALID_PRICE, the same guard the stops already had.
- positive_float raised OverflowError on 10**400. It now returns None, so
  every Result path stays non-raising, including the legacy offset stop.
- Stop.parse(value, kind) -> Result is the non-raising way to build a stop
  from a value that may be bad at runtime, e.g. an ATR that is NaN during
  warm-up. stop_input and legacy_stop use it, so legacy no longer catches
  ValueError for control flow. The constructors still raise: a Stop of 0
  cannot exist, and that is the one case where the project rules allow a
  domain exception. Rejected alternative: making the constructors return a
  Result, which would turn `sl=Stop.points(1000)` into an unwrap at every
  call site.
- Stop(1000, "points") (a str instead of a StopKind) was silently a PRICE
  stop. It now raises TypeError.
- The retry policy is derived from e.price, the same source build() uses.
- README, ADR 0008 and CHANGELOG describe the raising and the non-raising
  path. StopKind is exported for Stop.parse.

Not changed:
- Entry.request(quote=None) stays. A priced entry ignores the quote by
  design, and a missing price is an explicit NO_PRICE Err, covered by a
  test.
- as_dict stays a projection of as_object. The comment now names sl/tp as
  the one intended difference.

RED: the 4 new tests failed before the change.
Fourth /code-review high round, on 591f1cb:

- price=1e305, a limit at 1e305 and sl/tp=1e305 raised OverflowError.
  They passed the number rule (finite), then 1e305 / 1e-5 overflowed to
  inf in normalize_price and round(inf) raised. SymbolSpec.price_on_grid
  is now the single place every sent level (entry price, sl, tp) goes on
  the grid. It returns Err on overflow, on a level that snaps to 0 or
  below, and on a symbol with neither tick size nor point. This replaces
  the two ad-hoc "normalize, then check <= 0" copies, which had already
  diverged: neither one guarded the overflow. Stop.stop_loss/take_profit
  return a Result accordingly.
- Stop.parse(0, "points") raised AttributeError and Stop.parse(5,
  "points") raised TypeError. The kind check now runs first, inside the
  shared _checked, so a wrong kind is always a TypeError.
- positive_float catches only OverflowError, the one named case. Catching
  ValueError would have hidden bugs in a caller's own number type, with a
  misleading message and no traceback.
- README, ADR 0008 and CHANGELOG now say exactly what the Stop
  constructors raise on, and how large finite floats are handled.

Not changed: Stop.parse validates once in _checked and again in
__post_init__. Both calls go through the same function, so they cannot
diverge, and the alternative of catching ValueError is the exception-driven
control flow the previous round removed.

RED: the overflow and parse-kind tests failed before the change. The
test_stops expectations moved to Ok(...) with the new return type.
…before quotes

Fifth /code-review high round, on 048ab75:

- With point=inf (and tick_size=0), price_on_grid returned Ok(nan) and an
  order priced NaN was sent. With point=0, Stop.points(1000) resolved to
  the entry price. SymbolSpec now has an invariant: point, volume_step and
  volume_min must be positive and finite, tick_size must be 0 or positive
  and finite, volume_max must be >= volume_min, and digits >= 0.
  __post_init__ raises, because such a spec cannot exist, and the adapter
  goes through SymbolSpec.check, which turns broken data into
  Err(TERMINAL_ERROR). This removes the scattered step guards in
  validate_volume and price_on_grid. They are unreachable now, and they
  had already missed the inf case. The step choice lives once, in _step.
- Absolute sl/tp are checked on the grid in validate_entry. A stop that can
  never be valid no longer waits through the NO_PRICE retries of a symbol
  without quotes before it is reported.
- positive_float catches ArithmeticError (overflow, and numpy
  FloatingPointError under seterr), which covers numbers out of range. It
  still lets ValueError/TypeError through: those are bugs in the caller's
  own type.
- The price_on_grid docstring and ADR 0008 no longer claim that quote
  prices pass through it. A stops.py comment now states the decision.

Not changed:
- Stop.parse raises TypeError on a kind that is not a StopKind. A config
  string has to go through StopKind(...) first, which raises ValueError by
  itself.
- Stop.stop_loss/take_profit returning a Result needs no migration note:
  Stop is new in 3.0, which is unreleased.

RED: all 19 cases in the new test_symbol_data.py failed before the change.
The two tests that built impossible specs (volume_step=0, point=0) were
replaced by adapter-level tests, because such specs can no longer be built.
Sixth /code-review high round found a regression in a0f2aba, my own
commit. Its constructor invariant on SymbolSpec made the adapter refuse
the whole symbol, so close_positions() could no longer flatten a position
on a symbol with odd data (volume_step 0, point 0), although closing needs
only filling_flags. That is the most safety-critical path, so the
invariant is removed and each field is checked where it is used:

- price_on_grid refuses a step (tick size, else point) that is not
  positive and finite.
- SymbolSpec.points_to_price refuses a point that is not positive and
  finite, for points stops only. A symbol with a valid tick size and
  point 0 can still trade absolute prices.
- validate_volume refuses unusable min/max/step as INVALID_VOLUME. That is
  the error kind callers saw before a0f2aba, not TERMINAL_ERROR.
- The adapter refuses NaN and infinite quotes as NO_PRICE. `nan <= 0` is
  False, so a NaN ask was sent as the order price.
- A bad price is again reported before a bad absolute stop.

SymbolSpec.check and _problem are removed. A grep over src tests docs
*.md finds no remaining use. ADR 0008 records why the whole-spec
invariant was rejected.

Not changed: absolute stops are snapped once in validate_entry (as a
check) and again in Entry.request. That is the same pure function with
the same result, and keeping one resolution path avoids a second source
of truth for the sent level.

RED: on a0f2aba, 24 of the 27 cases in test_symbol_data.py failed,
including all 9 close cases. The FloatingPointError case already passed
there and pins the ArithmeticError catch.
…a close

Seventh /code-review high round, on 098ac0a:

- A NaN or negative tick size silently fell back to `point`, and negative
  digits rounded to tens (5785.25 -> 5790.0). Both have been checked since
  a0f2aba removed the constructor invariant.
- A market order without price or stops on a symbol with no usable step
  was still sent, because it never reaches price_on_grid. Every entry now
  calls SymbolSpec.check_tradable() first, which checks tick size, step,
  digits and volume limits. Closing never calls it.
- Broken data was reported as INVALID_PRICE / INVALID_STOPS /
  INVALID_VOLUME, which blames the caller, so a bot would drop signals
  instead of escalating. It is now TERMINAL_ERROR with "broken symbol
  data" in the message.
- normalize_price is folded into price_on_grid. As a public method it
  raised ZeroDivisionError or returned NaN on broken data. A grep over src
  tests docs README.md MIGRATION.md CHANGELOG.md finds no remaining use.
- _usable drops runtime type checks the float-typed fields never needed.
- An adapter-level test pins that broken symbol_info is passed on, not
  refused, so the a0f2aba close regression cannot come back through the
  adapter. CHANGELOG and ADR 0008 now describe what is actually refused.

RED: on 098ac0a, 16 of the 34 cases in test_symbol_data.py failed (the new
pricing cases, the market order without stops, and the error kinds).
…bol lookup

Eighth /code-review high round, on a11a618. Only findings that send an
unasked order, block a close, raise out of a Result boundary, or regress
this branch are fixed here. The rest are listed in the PR as debt.

- Broken symbol data came back as TERMINAL_ERROR, which ADR 0003 defines
  as "never sent, safe to resend". A bot following that rule would resend
  forever, because broken data does not clear. It now has its own kind,
  BROKEN_SYMBOL_DATA (escalate, don't retry). The README error table says
  so.
- check_tradable ran after validate_volume, so broken data plus an
  out-of-range volume came back as the caller's INVALID_VOLUME. It now
  runs right after the symbol lookup (_tradable_spec), the one place every
  entry passes through.
- _usable lost its type check in a11a618, so a hand-built spec with
  point=None raised TypeError out of check_tradable. The check is
  restored.

RED: against a11a618's src, 18 of the 54 cases in test_symbol_data.py and
test_symbol.py failed (the new kind, the precedence and the None point).
The owner asked to keep the MT5 functions in the package. The 2.x README
itself called `symbol_info("EURUSD")` after `from PythonMetaTrader5
import *`, so scripts written from it would hit NameError after a plain
`pip install -U`.

- legacy/mt5_namespace.py loads MetaTrader5 when it is installed and lists
  its public names. __init__ adds them as package attributes and to
  __all__. Our names win a collision: today only `Tick`, where MT5 has its
  own tick struct. Without the package (Linux, macOS, CI) nothing is
  added and the import still works.
- time, loguru's logger and pyautogui, which 2.x also leaked, are not
  restored. Two are no longer dependencies, and a leaked stdlib module is
  not an API.
- ADR 0010 supersedes the "drop the star re-export" part of ADR 0006 and
  records the remaining cost: new MT5 names enter our namespace, and
  MetaTrader5 is now imported eagerly. Importing it does not attach to a
  terminal; only initialize() does.
- MIGRATION, CHANGELOG and README now describe the star import as it is.

RED: the unit tests failed on the missing module, and the contract star
import test failed with KeyError 'symbol_info'.
…on lock

/code-review high on f3f835c found that the first draft was too shallow:

- A broken MT5 install (DLL load failure, missing numpy) was hidden. Any
  ImportError meant "re-export nothing", and the user later got a NameError
  on symbol_info, far from the cause. Now only "MetaTrader5 is not
  installed" means no names. Any other import failure raises where an MT5
  name is used, and the adapter reports it as "installed but cannot be
  imported" instead of "not installed".
- The eager import made every `import PythonMetaTrader5`, even of domain
  types only, pay for MT5 and numpy (65 of 87 ms) and fail with them. The
  package now has a PEP 562 __getattr__: MT5 names resolve on first use,
  and a star import gets __all__ through the same hook. Our own names
  stay plain attributes and win (Tick). They are re-exported with `X as X`
  because __all__ is computed.
- Re-exported functions bypassed the adapter's lock, so a direct
  last_error() could interleave with the adapter's order_send and make a
  lost order look "never sent". They are now wrapped to hold the same
  lock. adapters/mt5_session.py holds that lock and the one MetaTrader5
  import site, shared by the adapter and the re-export, so the two can no
  longer diverge.
- The wiring is unit-tested with the fake module: the star import, the
  lock, missing vs broken installs, dir(), no eager import, and that
  time/logger/pyautogui stay absent. The contract test checks the real
  package.
- ADR 0010 records the lazy design and the typing cost: __getattr__
  returns Any, so typos on the package root no longer fail type checks.
  ADR 0006's title marks the superseded part. The CHANGELOG moves the
  namespace from Removed to Changed. ADR 0009, architecture.md, MIGRATION
  and README mention the lock.

Removed names (mt5_namespace.load, mt5_terminal._SESSION, _reexported):
grep over src tests docs *.md finds no remaining use.

RED: the new unit tests failed on the missing mt5_session module.
…ays why

/code-review high on 05e3c35. Fixed: the findings that raise out of a
Result boundary or regress this branch.

- On a broken install, `from PythonMetaTrader5 import *` raised
  ImportError, even for scripts that only use connect(). hasattr(),
  getattr(.., default) and dir() raised as well, which breaks IDEs and
  pydoc. Now the star import keeps our names and emits a RuntimeWarning
  with the cause. An MT5 name raises AttributeError chained to the
  ImportError, so hasattr is False and the cause is kept. connect() returns
  Err(CONNECTION_FAILED).
- An AttributeError or ValueError raised while MetaTrader5 imported (numpy
  ABI mismatch) escaped. The AttributeError read as "no __all__" and
  silently emptied the star import; others escaped connect() as raw
  exceptions. import_metatrader5 now turns every failure except "not
  installed" into ImportError with the cause, and the adapter already
  maps ImportError to Err.
- Dead `taken` parameter dropped: a module __getattr__ only runs on
  misses. The collision filter for __all__ stays in __init__, where it
  takes effect. The `_serialized` alias and its comment are gone; methods
  use `@serialized`.
- MIGRATION, README and ADR 0010 no longer claim that re-exported calls
  "cannot interleave". The lock covers one call, not a script's own
  order_send + last_error pair.
- Tests patch mt5_session's importlib reference instead of the stdlib
  module, and cover ImportError, ModuleNotFoundError of a dependency,
  AttributeError and ValueError.

Debt (ADR 0010): resolved names and the "not installed" outcome are not
cached, so each access re-resolves. This affects performance and
identity, not correctness.

RED: 4 cases in test_mt5_namespace.py failed before the change.
…aveat

Follow-up to the /code-review high findings on d046e6a. These are small,
mechanical fixes and get no separate review round. The PR says so.

- connect() on a broken install said "installed but cannot be imported"
  twice. load() now passes import_metatrader5's message through, and the
  test pins the exact text.
- The RuntimeWarning used stacklevel 3 and so pointed at the library's
  __getattr__. It now uses 4 and names the user's import line.
- import_metatrader5 has one except clause and one raise instead of two
  identical ones.
- CHANGELOG gets the per-call lock caveat that README, MIGRATION and ADR
  0010 already carry.
- ADR 0010 lists the remaining debt: no caching of the import outcome, and
  on a broken install hasattr/getattr(..., None) do not warn while star
  import and dir() do.
@Akinzou
Akinzou merged commit 69ef5d1 into master Nov 9, 2026
8 checks passed
@Akinzou
Akinzou deleted the rewrite/v3 branch November 14, 2026 01:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant