Coverage for src/PythonMetaTrader5/application/trader.py: 100%
117 statements
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-12 12:29 +0000
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-12 12:29 +0000
1"""Trading use cases: open, close, place and cancel orders, query state."""
3from __future__ import annotations
5from dataclasses import replace
6from types import TracebackType
8from PythonMetaTrader5.application import magic_scope
9from PythonMetaTrader5.application.batch import BatchFailure, run_batch, with_magic
10from PythonMetaTrader5.application.entries import StopInput, validate_entry
11from PythonMetaTrader5.application.execution import RetryPolicy, execute
12from PythonMetaTrader5.application.ports import Clock, Terminal
13from PythonMetaTrader5.domain.errors import TradeError
14from PythonMetaTrader5.domain.inputs import (
15 ANY_MAGIC,
16 AnyMagic,
17 magic_filter,
18 own_magic,
19 symbol_filter,
20 ticket_filter,
21)
22from PythonMetaTrader5.domain.market import PendingKind, PendingOrder, Position, TradeReceipt
23from PythonMetaTrader5.domain.orders import Side, validate_comment
24from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest
25from PythonMetaTrader5.domain.symbol import SymbolSpec
26from PythonMetaTrader5.result import Err, Ok, Result
29class Trader:
30 """Trading calls on one logged-in account; get one from `connect`.
32 Every trading call and query returns a `Result`. Orders carry the trader's ``magic``, and
33 close-all / cancel-all act only on it unless told otherwise. A context
34 manager: ``with trader:`` shuts the connection down on exit. Tests build one
35 directly from fakes of the ``Terminal`` and ``Clock`` ports.
36 """
38 def __init__(
39 self,
40 terminal: Terminal,
41 clock: Clock,
42 *,
43 magic: int = 0,
44 deviation: int = 10,
45 retry: RetryPolicy | None = None,
46 ) -> None:
47 self._terminal = terminal
48 self._clock = clock
49 own = own_magic(magic)
50 if isinstance(own, Err):
51 # A constructor cannot return a Result; connect() reports this as Err.
52 raise ValueError(own.error.message)
53 self._magic = own.value
54 self._deviation = deviation
55 self._retry = retry or RetryPolicy()
57 # ------------------------------------------------------------------ entries
59 def open_position(
60 self,
61 symbol: str,
62 side: Side | str,
63 volume: float,
64 *,
65 sl: StopInput = None,
66 tp: StopInput = None,
67 price: float | None = None,
68 comment: str | None = None,
69 ) -> Result[TradeReceipt, TradeError]:
70 """Open a market position; ``sl``/``tp`` floats are prices, ``Stop.points`` distances.
72 Without ``price`` the current quote is used and requotes are retried with a
73 fresh quote. An explicit ``price`` is sent once: re-sending the same price
74 after a requote cannot succeed.
75 """
76 entry = validate_entry(
77 self._terminal, symbol, side, volume, comment=comment, sl=sl, tp=tp, price=price
78 )
79 if isinstance(entry, Err):
80 return entry
81 e = entry.value
83 def build() -> Result[OrderRequest | CancelRequest, TradeError]:
84 quote = None
85 if e.price is None:
86 tick = self._terminal.tick(symbol)
87 if isinstance(tick, Err):
88 return tick
89 quote = tick.value.entry_price(e.side)
90 return e.request(quote, pending=None, deviation=self._deviation, magic=self._magic)
92 policy = self._retry if e.price is None else replace(self._retry, attempts=1)
93 return execute(self._terminal, self._clock, build, policy)
95 def place_limit_order(
96 self,
97 symbol: str,
98 side: Side | str,
99 volume: float,
100 price: float,
101 *,
102 sl: StopInput = None,
103 tp: StopInput = None,
104 comment: str | None = None,
105 ) -> Result[TradeReceipt, TradeError]:
106 """Place a BUY/SELL LIMIT at ``price``; point stops are measured from that level.
108 A limit on the wrong side of the market is refused by the server
109 (INVALID_PRICE) rather than converted into a market order.
110 """
111 entry = validate_entry(
112 self._terminal,
113 symbol,
114 side,
115 volume,
116 comment=comment,
117 sl=sl,
118 tp=tp,
119 price=price,
120 price_required=True,
121 )
122 if isinstance(entry, Err):
123 return entry
124 request = entry.value.request(
125 pending=PendingKind.LIMIT, deviation=self._deviation, magic=self._magic
126 )
127 if isinstance(request, Err):
128 return request
129 return execute(self._terminal, self._clock, lambda: request, self._retry)
131 # ------------------------------------------------------------------- exits
133 def close_positions(
134 self,
135 symbol: str | None = None,
136 *,
137 ticket: int | None = None,
138 magic: int | AnyMagic | None = None,
139 comment: str | None = None,
140 ) -> Result[list[TradeReceipt], BatchFailure]:
141 """Close matching positions; ``ticket`` takes precedence over ``symbol``.
143 Only the trader's own ``magic`` unless another ``magic`` is given;
144 ``magic=ANY_MAGIC`` closes every position, manual ones included. A
145 ``ticket`` is closed whatever its magic.
146 """
147 text = validate_comment(comment)
148 if isinstance(text, Err):
149 return Err(BatchFailure((), (text.error,)))
150 own = magic_scope.resolve(self._magic, magic, ticket)
151 if isinstance(own, Err):
152 return Err(BatchFailure((), (own.error,)))
153 listed = self.positions(
154 None if ticket is not None else symbol, ticket=ticket, magic=own.value
155 )
156 if isinstance(listed, Err):
157 return Err(BatchFailure((), (listed.error,)))
158 scope = None if ticket is not None else symbol
159 magic_scope.warn_about_default(
160 self._magic, magic, ticket, listed.value, lambda: self.positions(scope, magic=ANY_MAGIC)
161 )
162 # One spec lookup per symbol, not per position: close-all is time-critical.
163 specs: dict[str, Result[SymbolSpec, TradeError]] = {}
165 def close(position: Position) -> Result[TradeReceipt, TradeError]:
166 if position.symbol not in specs:
167 specs[position.symbol] = self._terminal.symbol(position.symbol)
168 return self._close_one(position, specs[position.symbol], text.value)
170 return run_batch(listed.value, close)
172 def cancel_pending_orders(
173 self,
174 symbol: str | None = None,
175 *,
176 magic: int | AnyMagic | None = None,
177 kind: PendingKind | None = None,
178 ) -> Result[list[TradeReceipt], BatchFailure]:
179 """Cancel matching pending orders of the trader's own ``magic`` by default.
181 ``magic=ANY_MAGIC`` cancels every order on the account, manual ones included.
182 """
183 own = magic_scope.resolve(self._magic, magic, None)
184 if isinstance(own, Err):
185 return Err(BatchFailure((), (own.error,)))
186 listed = self.pending_orders(symbol, magic=own.value, kind=kind)
187 if isinstance(listed, Err):
188 return Err(BatchFailure((), (listed.error,)))
189 magic_scope.warn_about_default(
190 self._magic,
191 magic,
192 None,
193 listed.value,
194 lambda: self.pending_orders(symbol, magic=ANY_MAGIC, kind=kind),
195 )
196 return run_batch(listed.value, self._cancel_one)
198 # ----------------------------------------------------------------- queries
200 def positions(
201 self,
202 symbol: str | None = None,
203 *,
204 ticket: int | None = None,
205 magic: int | AnyMagic | None = None,
206 ) -> Result[list[Position], TradeError]:
207 """Every position by default: a read never needs the own-magic guard."""
208 checked = magic_filter(magic)
209 if isinstance(checked, Err):
210 return checked
211 for check in (symbol_filter(symbol), ticket_filter(ticket)):
212 if isinstance(check, Err):
213 return check
214 listed = self._terminal.positions(symbol=symbol, ticket=ticket)
215 if isinstance(listed, Err):
216 return listed
217 return Ok(with_magic(listed.value, checked.value))
219 def pending_orders(
220 self,
221 symbol: str | None = None,
222 *,
223 magic: int | AnyMagic | None = None,
224 kind: PendingKind | None = None,
225 ) -> Result[list[PendingOrder], TradeError]:
226 """Every pending order by default, optionally only one ``kind``."""
227 checked = magic_filter(magic)
228 if isinstance(checked, Err):
229 return checked
230 symbol_checked = symbol_filter(symbol)
231 if isinstance(symbol_checked, Err):
232 return symbol_checked
233 listed = self._terminal.pending_orders(symbol=symbol)
234 if isinstance(listed, Err):
235 return listed
236 orders = with_magic(listed.value, checked.value)
237 return Ok(orders if kind is None else [o for o in orders if o.kind is kind])
239 def shutdown(self) -> None:
240 """Close the connection to the terminal."""
241 self._terminal.shutdown()
243 def __enter__(self) -> Trader:
244 return self
246 def __exit__(
247 self,
248 exc_type: type[BaseException] | None,
249 exc: BaseException | None,
250 tb: TracebackType | None,
251 ) -> None:
252 self.shutdown()
254 # ----------------------------------------------------------------- helpers
256 def _close_one(
257 self, position: Position, spec: Result[SymbolSpec, TradeError], comment: str
258 ) -> Result[TradeReceipt, TradeError]:
259 if isinstance(spec, Err):
260 return spec
261 filling = spec.value.market_filling()
263 def build() -> Result[OrderRequest | CancelRequest, TradeError]:
264 tick = self._terminal.tick(position.symbol)
265 if isinstance(tick, Err):
266 return tick
267 return Ok(
268 OrderRequest(
269 symbol=position.symbol,
270 side=position.side.opposite,
271 volume=position.volume,
272 price=tick.value.exit_price(position.side),
273 filling=filling,
274 deviation=self._deviation,
275 magic=self._magic,
276 comment=comment,
277 position=position.ticket,
278 )
279 )
281 return execute(self._terminal, self._clock, build, self._retry)
283 def _cancel_one(self, order: PendingOrder) -> Result[TradeReceipt, TradeError]:
284 request = CancelRequest(order=order.ticket)
285 return execute(self._terminal, self._clock, lambda: Ok(request), self._retry)