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

1"""Trading use cases: open, close, place and cancel orders, query state.""" 

2 

3from __future__ import annotations 

4 

5from dataclasses import replace 

6from types import TracebackType 

7 

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 

27 

28 

29class Trader: 

30 """Trading calls on one logged-in account; get one from `connect`. 

31 

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 """ 

37 

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() 

56 

57 # ------------------------------------------------------------------ entries 

58 

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. 

71 

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 

82 

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) 

91 

92 policy = self._retry if e.price is None else replace(self._retry, attempts=1) 

93 return execute(self._terminal, self._clock, build, policy) 

94 

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. 

107 

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) 

130 

131 # ------------------------------------------------------------------- exits 

132 

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``. 

142 

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]] = {} 

164 

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) 

169 

170 return run_batch(listed.value, close) 

171 

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. 

180 

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) 

197 

198 # ----------------------------------------------------------------- queries 

199 

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)) 

218 

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]) 

238 

239 def shutdown(self) -> None: 

240 """Close the connection to the terminal.""" 

241 self._terminal.shutdown() 

242 

243 def __enter__(self) -> Trader: 

244 return self 

245 

246 def __exit__( 

247 self, 

248 exc_type: type[BaseException] | None, 

249 exc: BaseException | None, 

250 tb: TracebackType | None, 

251 ) -> None: 

252 self.shutdown() 

253 

254 # ----------------------------------------------------------------- helpers 

255 

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() 

262 

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 ) 

280 

281 return execute(self._terminal, self._clock, build, self._retry) 

282 

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)