Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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]

Expand Down
4 changes: 2 additions & 2 deletions MIGRATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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 |

Expand Down
6 changes: 4 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
29 changes: 21 additions & 8 deletions src/PythonMetaTrader5/domain/orders.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
41 changes: 39 additions & 2 deletions tests/integration/test_demo_account.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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")
Expand Down Expand Up @@ -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
2 changes: 1 addition & 1 deletion tests/unit/test_failure_paths.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 == []
Expand Down
31 changes: 27 additions & 4 deletions tests/unit/test_orders.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading