diff --git a/CHANGELOG.md b/CHANGELOG.md index df2ca96..b5fd8e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -79,6 +79,9 @@ Complete rewrite. See [MIGRATION.md](MIGRATION.md) for every behaviour change. - `CancelOrders` and `Close` could loop forever. - Limit orders confirmed with `PLACED` (10008) were re-sent. - `len(None)` crash when the terminal returned no positions. +- Comments of 30 or more UTF-16 units (most emoji count as 2), which the + `MetaTrader5` package refuses although its docs allow 31, and comments that + are not `str`, are refused locally as `INVALID_ARGUMENT`. ## [2.3.2] diff --git a/MIGRATION.md b/MIGRATION.md index 6c1b027..a606018 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -28,7 +28,7 @@ upgrading a bot that trades real money. | 2.x | 3.0 | Why | |---|---|---| | `OpenPosition`, `Buy*`, `Sell*`, `BuyLimit`, `SellLimit` retried **forever** on any unknown retcode (no money, invalid volume, market closed over the weekend), sending an order every 0.5 s | Requotes are retried at most 3 times. Any other broker refusal returns at once: the receipt is returned and the error is logged | A weekend webhook blocked the bot until Monday; a rejected order was re-sent indefinitely | -| Invalid input was sent anyway and then retried forever | Refused **before sending**: the call returns `None`, not a receipt, and logs why. This covers a volume off the lot step or outside min/max, an unknown symbol, a comment over 31 characters, and the cases below. Check for `None` before reading `.retcode` | Nothing was sent, so there is no broker answer to return | +| Invalid input was sent anyway and then retried forever | Refused **before sending**: the call returns `None`, not a receipt, and logs why. This covers a volume off the lot step or outside min/max, an unknown symbol, a comment over 29 UTF-16 units (most emoji count as 2), and the cases below. Check for `None` before reading `.retcode` | Nothing was sent, so there is no broker answer to return | | `sl=0` / `tp=0` sent 0.0, which MT5 reads as "no stop" | Refused (returns `None`). Pass `None`, or leave the argument out, for no stop | A missing SL field in a webhook opened an unprotected position without any error | | An unknown `sl_type` / `tp_type` (e.g. `"bogus"`) opened the position with **neither SL nor TP** | Opens nothing, returns `None` and logs the error | The stop the caller asked for was silently dropped | | `volume=True` was traded as 1 lot; NaN or infinite numbers crashed deep inside | Refused (returns `None`). Numeric strings (`"0.1"`) are still converted as in 2.x | A stray bool must not become one lot | @@ -37,7 +37,7 @@ upgrading a bot that trades real money. | A partial or only-queued (PLACED) market entry counted as opened | Logged as an error; the receipt is still returned, so check `receipt.retcode` (10009 = done) | The bot believed it held the full size | | Retcode 10008 (`PLACED`) for limit orders was treated as failure and re-sent | Treated as success | Limit orders could be placed more than once | | `ticket=` on `OpenPosition`/`Buy`/`Sell`/`BuyLimit`/`SellLimit` was forwarded as `position` | Refused: returns `None`, logs an error | On hedging accounts it turned an entry into a close of that position | -| Comments longer than 31 characters made `order_send` fail with `None` | Rejected before sending, logged | Explicit error instead of a crash downstream | +| Comments the `MetaTrader5` package refuses (30+ UTF-16 units on 5.0.6231; its docs say 31) made `order_send` fail with `None` | Rejected before sending, logged | Explicit error instead of a crash downstream | | Prices rounded to `digits` | Prices snapped to the symbol's tick size | Symbols with tick 0.25 were rejected | | Fixed filling: FOK for market entries, IOC for closes and limit orders | Filling chosen from the symbol's allowed modes (FOK > IOC > RETURN); limit orders on exchange-execution symbols use RETURN | Brokers without FOK rejected every order (10030); IOC cancelled exchange limits unless instantly fillable | diff --git a/README.md b/README.md index 9fe4941..4789797 100644 --- a/README.md +++ b/README.md @@ -112,8 +112,10 @@ deviation=10, retry=None) -> Result[Trader, TradeError]` - 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 31 characters (the terminal's limit). Longer comments are - rejected, not truncated. +- `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()` 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. diff --git a/src/PythonMetaTrader5/domain/orders.py b/src/PythonMetaTrader5/domain/orders.py index 338dd2d..6e4fc4b 100644 --- a/src/PythonMetaTrader5/domain/orders.py +++ b/src/PythonMetaTrader5/domain/orders.py @@ -34,18 +34,31 @@ def parse(cls, value: Side | str) -> Result[Side, TradeError]: return Ok(cls[name]) -# The terminal stores at most 31 characters and answers longer comments with an -# "Invalid comment argument" error instead of trimming them. -MAX_COMMENT_LENGTH = 31 +# Measured with order_check, not taken from the docs: MetaTrader5 5.0.6231 +# accepts 29 UTF-16 code units and refuses 30 with [-2] Invalid "comment" +# argument before sending. The documented 31 would let 30-31 through to a +# TERMINAL_ERROR that hides the cause, and trimming would change what the user +# asked to store. tests/integration re-measures it when the package changes. +MAX_COMMENT_LENGTH = 29 -def validate_comment(comment: str | None) -> Result[str, TradeError]: - text = comment or "" - if len(text) > MAX_COMMENT_LENGTH: +def validate_comment(comment: object) -> Result[str, TradeError]: + if comment is None: + return Ok("") + # `comment or ""` would store 0 or False as an empty comment without a word. + if not isinstance(comment, str): + return Err(TradeError(ErrorKind.INVALID_ARGUMENT, f"comment must be text, not {comment!r}")) + # The package counts UTF-16 units, not len(): "\U0001f680" * 15 is refused. + # surrogatepass: the package accepts a lone surrogate (measured), so it is + # one unit here, not a UnicodeEncodeError. + units = len(comment.encode("utf-16-le", "surrogatepass")) // 2 + if units > MAX_COMMENT_LENGTH: return Err( TradeError( ErrorKind.INVALID_ARGUMENT, - f"comment is {len(text)} characters; the terminal accepts {MAX_COMMENT_LENGTH}", + f"comment is {units} UTF-16 units (characters outside the BMP, such as " + f"most emoji, count as 2; combined emoji more); " + f"the MetaTrader5 package accepts at most {MAX_COMMENT_LENGTH}", ) ) - return Ok(text) + return Ok(comment) diff --git a/tests/integration/test_demo_account.py b/tests/integration/test_demo_account.py index 7892540..166d439 100644 --- a/tests/integration/test_demo_account.py +++ b/tests/integration/test_demo_account.py @@ -18,6 +18,7 @@ import pytest from PythonMetaTrader5 import Err, ErrorKind, Ok, PendingKind, Side, Stop, Trader, connect +from PythonMetaTrader5.domain.orders import MAX_COMMENT_LENGTH pytestmark = pytest.mark.integration # Windows-only package: the whole module is skipped where it cannot be installed. @@ -63,7 +64,8 @@ def test_open_and_close_a_market_position(trader: Trader) -> None: minimum_volume(), sl=Stop.points(2000), tp=Stop.points(2000), - comment="pmt5 integration", + # The longest comment we let through must be accepted for real. + comment="pmt5 integration".ljust(MAX_COMMENT_LENGTH, "."), ) if isinstance(opened, Err) and opened.error.kind is ErrorKind.MARKET_CLOSED: pytest.skip("market closed") @@ -94,6 +96,41 @@ def test_place_and_cancel_a_limit_order_far_from_the_market(trader: Trader) -> N def test_oversized_comment_is_rejected_locally(trader: Trader) -> None: - result = trader.open_position(SYMBOL, Side.BUY, minimum_volume(), comment="x" * 32) + result = trader.open_position(SYMBOL, Side.BUY, minimum_volume(), comment="x" * 30) assert isinstance(result, Err) assert result.error.kind is ErrorKind.INVALID_ARGUMENT + + +@pytest.mark.parametrize( + ("comment", "accepted"), + [ + ("x" * MAX_COMMENT_LENGTH, True), + ("x" * (MAX_COMMENT_LENGTH + 1), False), + # 15 characters but 30 UTF-16 units: tells unit counting from len(). + ("\U0001f680" * 14 + "x", True), + ("\U0001f680" * 15, False), + ], +) +def test_comment_limit_matches_the_installed_package( + trader: Trader, comment: str, accepted: bool +) -> None: + # order_check validates without sending. MAX_COMMENT_LENGTH is a measurement + # of one package build, so a package that moves the boundary fails here. + tick = mt5.symbol_info_tick(SYMBOL) + request = { + "action": mt5.TRADE_ACTION_DEAL, + "symbol": SYMBOL, + "volume": minimum_volume(), + "type": mt5.ORDER_TYPE_BUY, + "price": tick.ask, + "comment": comment, + } + checked = mt5.order_check(request) + code, message = mt5.last_error() + if accepted: + assert checked is not None, (code, message) + else: + # Refused for the comment, not for a dropped link or a closed market. + assert checked is None + assert code == mt5.RES_E_INVALID_PARAMS, (code, message) + assert "comment" in message, message diff --git a/tests/unit/test_failure_paths.py b/tests/unit/test_failure_paths.py index 25dc4d7..7a3892b 100644 --- a/tests/unit/test_failure_paths.py +++ b/tests/unit/test_failure_paths.py @@ -44,7 +44,7 @@ def test_close_rejects_overlong_comment_before_touching_positions( trader: Trader, terminal: FakeTerminal ) -> None: terminal.open_positions = [btc_position()] - result = trader.close_positions(comment="c" * 32) + result = trader.close_positions(comment="c" * 30) assert isinstance(result, Err) assert result.error.errors[0].kind is ErrorKind.INVALID_ARGUMENT assert terminal.sent == [] diff --git a/tests/unit/test_orders.py b/tests/unit/test_orders.py index ec67c67..2455c08 100644 --- a/tests/unit/test_orders.py +++ b/tests/unit/test_orders.py @@ -25,12 +25,35 @@ def test_side_has_opposite() -> None: assert Side.SELL.opposite is Side.BUY -def test_comment_within_terminal_limit_is_kept() -> None: +# Boundaries measured with order_check on MetaTrader5 5.0.6231 (demo account): +# the package counts UTF-16 code units. 29 pass, 30 get [-2] Invalid "comment" +# argument, whether ASCII, Polish, CJK (1 unit each) or emoji (2 units each). +# It also accepts a lone surrogate, so that counts as one unit. +@pytest.mark.parametrize( + "comment", + ["x" * 29, "\u0142" * 29, "\u4e2d" * 29, "\U0001f680" * 14 + "x", "\ud83d" * 29], +) +def test_comment_within_package_limit_is_kept(comment: str) -> None: + assert validate_comment(comment) == Ok(comment) + + +def test_missing_comment_is_empty() -> None: assert validate_comment(None) == Ok("") - assert validate_comment("x" * 31) == Ok("x" * 31) -def test_comment_over_terminal_limit_is_rejected_not_truncated() -> None: - result = validate_comment("x" * 32) +@pytest.mark.parametrize( + "comment", + ["x" * 30, "\u0142" * 30, "\U0001f680" * 15, "\U0001f680" + "x" * 28], +) +def test_comment_over_package_limit_is_rejected_not_truncated(comment: str) -> None: + result = validate_comment(comment) + assert isinstance(result, Err) + assert result.error.kind is ErrorKind.INVALID_ARGUMENT + assert "at most 29" in result.error.message + + +@pytest.mark.parametrize("comment", [12345, 0, False, b"bytes"]) +def test_non_text_comment_is_rejected_not_blanked(comment: object) -> None: + result = validate_comment(comment) assert isinstance(result, Err) assert result.error.kind is ErrorKind.INVALID_ARGUMENT