Coverage for src/copytrading_engine/execution/domain/order_lifecycle.py: 98%

66 statements  

« prev     ^ index     » next       coverage.py v7.16.2, created at 2026-11-16 16:55 +0000

1"""Finite internal order states and guarded lifecycle transitions.""" 

2 

3from enum import StrEnum 

4 

5 

6class OrderStatus(StrEnum): 

7 """Local intent and Alpaca order states understood by the executor.""" 

8 

9 PREPARED = "prepared" 

10 UNCERTAIN = "uncertain" 

11 ABORTED_BEFORE_SUBMIT = "aborted_before_submit" 

12 RELEASED_UNSUBMITTED = "released_unsubmitted" 

13 

14 ACCEPTED = "accepted" 

15 PENDING_NEW = "pending_new" 

16 ACCEPTED_FOR_BIDDING = "accepted_for_bidding" 

17 NEW = "new" 

18 PARTIALLY_FILLED = "partially_filled" 

19 PENDING_CANCEL = "pending_cancel" 

20 PENDING_REPLACE = "pending_replace" 

21 STOPPED = "stopped" 

22 SUSPENDED = "suspended" 

23 HELD = "held" 

24 DONE_FOR_DAY = "done_for_day" 

25 

26 FILLED = "filled" 

27 CANCELED = "canceled" 

28 EXPIRED = "expired" 

29 REPLACED = "replaced" 

30 REJECTED = "rejected" 

31 CALCULATED = "calculated" 

32 UNRECOGNIZED = "unrecognized" 

33 

34 

35_BROKER_STATUSES = frozenset( 

36 { 

37 OrderStatus.ACCEPTED, 

38 OrderStatus.PENDING_NEW, 

39 OrderStatus.ACCEPTED_FOR_BIDDING, 

40 OrderStatus.NEW, 

41 OrderStatus.PARTIALLY_FILLED, 

42 OrderStatus.PENDING_CANCEL, 

43 OrderStatus.PENDING_REPLACE, 

44 OrderStatus.STOPPED, 

45 OrderStatus.SUSPENDED, 

46 OrderStatus.HELD, 

47 OrderStatus.DONE_FOR_DAY, 

48 OrderStatus.FILLED, 

49 OrderStatus.CANCELED, 

50 OrderStatus.EXPIRED, 

51 OrderStatus.REPLACED, 

52 OrderStatus.REJECTED, 

53 OrderStatus.CALCULATED, 

54 } 

55) 

56 

57_PENDING = frozenset( 

58 { 

59 OrderStatus.PREPARED, 

60 OrderStatus.UNCERTAIN, 

61 OrderStatus.ACCEPTED, 

62 OrderStatus.PENDING_NEW, 

63 OrderStatus.ACCEPTED_FOR_BIDDING, 

64 OrderStatus.NEW, 

65 OrderStatus.PARTIALLY_FILLED, 

66 OrderStatus.PENDING_CANCEL, 

67 OrderStatus.PENDING_REPLACE, 

68 OrderStatus.STOPPED, 

69 OrderStatus.SUSPENDED, 

70 OrderStatus.HELD, 

71 OrderStatus.DONE_FOR_DAY, 

72 OrderStatus.CALCULATED, 

73 OrderStatus.UNRECOGNIZED, 

74 } 

75) 

76 

77_TERMINAL = frozenset( 

78 { 

79 OrderStatus.ABORTED_BEFORE_SUBMIT, 

80 OrderStatus.RELEASED_UNSUBMITTED, 

81 OrderStatus.FILLED, 

82 OrderStatus.CANCELED, 

83 OrderStatus.EXPIRED, 

84 OrderStatus.REPLACED, 

85 OrderStatus.REJECTED, 

86 } 

87) 

88 

89# A pending status does not always mean another cancel request is useful or safe. 

90# In particular, unknown states and requests already pending replacement stay put. 

91_CANCELABLE = frozenset( 

92 { 

93 OrderStatus.ACCEPTED, 

94 OrderStatus.PENDING_NEW, 

95 OrderStatus.ACCEPTED_FOR_BIDDING, 

96 OrderStatus.NEW, 

97 OrderStatus.PARTIALLY_FILLED, 

98 OrderStatus.STOPPED, 

99 OrderStatus.SUSPENDED, 

100 OrderStatus.HELD, 

101 OrderStatus.DONE_FOR_DAY, 

102 } 

103) 

104 

105_BROKER_TRANSITIONS: dict[OrderStatus, frozenset[OrderStatus]] = { 

106 OrderStatus.ACCEPTED: frozenset( 

107 { 

108 OrderStatus.PENDING_NEW, 

109 OrderStatus.ACCEPTED_FOR_BIDDING, 

110 OrderStatus.NEW, 

111 OrderStatus.PARTIALLY_FILLED, 

112 OrderStatus.PENDING_CANCEL, 

113 OrderStatus.PENDING_REPLACE, 

114 OrderStatus.STOPPED, 

115 OrderStatus.SUSPENDED, 

116 OrderStatus.HELD, 

117 OrderStatus.DONE_FOR_DAY, 

118 OrderStatus.FILLED, 

119 OrderStatus.CANCELED, 

120 OrderStatus.EXPIRED, 

121 OrderStatus.REPLACED, 

122 OrderStatus.REJECTED, 

123 OrderStatus.CALCULATED, 

124 } 

125 ), 

126 OrderStatus.PENDING_NEW: frozenset( 

127 { 

128 OrderStatus.ACCEPTED, 

129 OrderStatus.ACCEPTED_FOR_BIDDING, 

130 OrderStatus.NEW, 

131 OrderStatus.PARTIALLY_FILLED, 

132 OrderStatus.PENDING_CANCEL, 

133 OrderStatus.PENDING_REPLACE, 

134 OrderStatus.STOPPED, 

135 OrderStatus.SUSPENDED, 

136 OrderStatus.HELD, 

137 OrderStatus.DONE_FOR_DAY, 

138 OrderStatus.FILLED, 

139 OrderStatus.CANCELED, 

140 OrderStatus.EXPIRED, 

141 OrderStatus.REPLACED, 

142 OrderStatus.REJECTED, 

143 OrderStatus.CALCULATED, 

144 } 

145 ), 

146 OrderStatus.ACCEPTED_FOR_BIDDING: frozenset( 

147 { 

148 OrderStatus.NEW, 

149 OrderStatus.PARTIALLY_FILLED, 

150 OrderStatus.PENDING_CANCEL, 

151 OrderStatus.PENDING_REPLACE, 

152 OrderStatus.STOPPED, 

153 OrderStatus.SUSPENDED, 

154 OrderStatus.HELD, 

155 OrderStatus.DONE_FOR_DAY, 

156 OrderStatus.FILLED, 

157 OrderStatus.CANCELED, 

158 OrderStatus.EXPIRED, 

159 OrderStatus.REPLACED, 

160 OrderStatus.REJECTED, 

161 OrderStatus.CALCULATED, 

162 } 

163 ), 

164 OrderStatus.NEW: frozenset( 

165 { 

166 OrderStatus.PARTIALLY_FILLED, 

167 OrderStatus.PENDING_CANCEL, 

168 OrderStatus.PENDING_REPLACE, 

169 OrderStatus.STOPPED, 

170 OrderStatus.SUSPENDED, 

171 OrderStatus.HELD, 

172 OrderStatus.DONE_FOR_DAY, 

173 OrderStatus.FILLED, 

174 OrderStatus.CANCELED, 

175 OrderStatus.EXPIRED, 

176 OrderStatus.REPLACED, 

177 OrderStatus.REJECTED, 

178 OrderStatus.CALCULATED, 

179 } 

180 ), 

181 OrderStatus.PARTIALLY_FILLED: frozenset( 

182 { 

183 OrderStatus.PENDING_CANCEL, 

184 OrderStatus.PENDING_REPLACE, 

185 OrderStatus.STOPPED, 

186 OrderStatus.SUSPENDED, 

187 OrderStatus.HELD, 

188 OrderStatus.DONE_FOR_DAY, 

189 OrderStatus.FILLED, 

190 OrderStatus.CANCELED, 

191 OrderStatus.EXPIRED, 

192 OrderStatus.REPLACED, 

193 OrderStatus.REJECTED, 

194 OrderStatus.CALCULATED, 

195 } 

196 ), 

197 OrderStatus.PENDING_CANCEL: frozenset( 

198 { 

199 OrderStatus.PARTIALLY_FILLED, 

200 OrderStatus.FILLED, 

201 OrderStatus.CANCELED, 

202 OrderStatus.EXPIRED, 

203 OrderStatus.REPLACED, 

204 OrderStatus.REJECTED, 

205 } 

206 ), 

207 OrderStatus.PENDING_REPLACE: frozenset( 

208 { 

209 OrderStatus.NEW, 

210 OrderStatus.PARTIALLY_FILLED, 

211 OrderStatus.PENDING_CANCEL, 

212 OrderStatus.STOPPED, 

213 OrderStatus.SUSPENDED, 

214 OrderStatus.HELD, 

215 OrderStatus.DONE_FOR_DAY, 

216 OrderStatus.FILLED, 

217 OrderStatus.CANCELED, 

218 OrderStatus.EXPIRED, 

219 OrderStatus.REPLACED, 

220 OrderStatus.REJECTED, 

221 OrderStatus.CALCULATED, 

222 } 

223 ), 

224 OrderStatus.STOPPED: frozenset( 

225 { 

226 OrderStatus.PARTIALLY_FILLED, 

227 OrderStatus.PENDING_CANCEL, 

228 OrderStatus.PENDING_REPLACE, 

229 OrderStatus.SUSPENDED, 

230 OrderStatus.DONE_FOR_DAY, 

231 OrderStatus.FILLED, 

232 OrderStatus.CANCELED, 

233 OrderStatus.EXPIRED, 

234 OrderStatus.REPLACED, 

235 OrderStatus.REJECTED, 

236 OrderStatus.CALCULATED, 

237 } 

238 ), 

239 OrderStatus.SUSPENDED: frozenset( 

240 { 

241 OrderStatus.NEW, 

242 OrderStatus.PARTIALLY_FILLED, 

243 OrderStatus.PENDING_CANCEL, 

244 OrderStatus.PENDING_REPLACE, 

245 OrderStatus.HELD, 

246 OrderStatus.DONE_FOR_DAY, 

247 OrderStatus.FILLED, 

248 OrderStatus.CANCELED, 

249 OrderStatus.EXPIRED, 

250 OrderStatus.REPLACED, 

251 OrderStatus.REJECTED, 

252 OrderStatus.CALCULATED, 

253 } 

254 ), 

255 OrderStatus.HELD: frozenset( 

256 { 

257 OrderStatus.NEW, 

258 OrderStatus.PARTIALLY_FILLED, 

259 OrderStatus.PENDING_CANCEL, 

260 OrderStatus.PENDING_REPLACE, 

261 OrderStatus.STOPPED, 

262 OrderStatus.SUSPENDED, 

263 OrderStatus.DONE_FOR_DAY, 

264 OrderStatus.FILLED, 

265 OrderStatus.CANCELED, 

266 OrderStatus.EXPIRED, 

267 OrderStatus.REPLACED, 

268 OrderStatus.REJECTED, 

269 OrderStatus.CALCULATED, 

270 } 

271 ), 

272 OrderStatus.DONE_FOR_DAY: frozenset( 

273 { 

274 OrderStatus.NEW, 

275 OrderStatus.PARTIALLY_FILLED, 

276 OrderStatus.PENDING_CANCEL, 

277 OrderStatus.PENDING_REPLACE, 

278 OrderStatus.STOPPED, 

279 OrderStatus.SUSPENDED, 

280 OrderStatus.HELD, 

281 OrderStatus.FILLED, 

282 OrderStatus.CANCELED, 

283 OrderStatus.EXPIRED, 

284 OrderStatus.REPLACED, 

285 OrderStatus.REJECTED, 

286 OrderStatus.CALCULATED, 

287 } 

288 ), 

289 OrderStatus.CALCULATED: frozenset( 

290 { 

291 OrderStatus.NEW, 

292 OrderStatus.PARTIALLY_FILLED, 

293 OrderStatus.PENDING_CANCEL, 

294 OrderStatus.PENDING_REPLACE, 

295 OrderStatus.STOPPED, 

296 OrderStatus.SUSPENDED, 

297 OrderStatus.HELD, 

298 OrderStatus.DONE_FOR_DAY, 

299 OrderStatus.FILLED, 

300 OrderStatus.CANCELED, 

301 OrderStatus.EXPIRED, 

302 OrderStatus.REPLACED, 

303 OrderStatus.REJECTED, 

304 } 

305 ), 

306} 

307 

308 

309def map_broker_status(raw_status: str) -> OrderStatus: 

310 """Map a vendor string into the finite internal status vocabulary.""" 

311 try: 

312 status = OrderStatus(raw_status) 

313 except ValueError: 

314 return OrderStatus.UNRECOGNIZED 

315 return status if status in _BROKER_STATUSES else OrderStatus.UNRECOGNIZED 

316 

317 

318def is_pending(status: OrderStatus) -> bool: 

319 return OrderStatus(status) in _PENDING 

320 

321 

322def is_terminal(status: OrderStatus) -> bool: 

323 return OrderStatus(status) in _TERMINAL 

324 

325 

326def is_cancelable(status: OrderStatus) -> bool: 

327 return OrderStatus(status) in _CANCELABLE 

328 

329 

330def is_valid_transition(previous: OrderStatus, current: OrderStatus) -> bool: 

331 previous = OrderStatus(previous) 

332 current = OrderStatus(current) 

333 if previous == current: 

334 return True 

335 if previous in {OrderStatus.PREPARED, OrderStatus.UNCERTAIN}: 

336 return ( 

337 current in _BROKER_STATUSES | {OrderStatus.UNRECOGNIZED} 

338 or ( 

339 previous == OrderStatus.PREPARED 

340 and current in {OrderStatus.UNCERTAIN, OrderStatus.ABORTED_BEFORE_SUBMIT} 

341 ) 

342 or (previous == OrderStatus.UNCERTAIN and current == OrderStatus.RELEASED_UNSUBMITTED) 

343 ) 

344 if previous == OrderStatus.RELEASED_UNSUBMITTED: 

345 return current in _BROKER_STATUSES | {OrderStatus.UNRECOGNIZED} 

346 if previous == OrderStatus.UNRECOGNIZED: 

347 return current in _BROKER_STATUSES | {OrderStatus.UNRECOGNIZED} 

348 if current == OrderStatus.UNRECOGNIZED and previous in _BROKER_STATUSES: 

349 return True 

350 if previous == OrderStatus.FILLED and current == OrderStatus.CALCULATED: 

351 return True 

352 if is_terminal(previous): 

353 return False 

354 if previous in _BROKER_TRANSITIONS: 354 ↛ 356line 354 didn't jump to line 356 because the condition on line 354 was always true

355 return current in _BROKER_TRANSITIONS[previous] | {OrderStatus.UNRECOGNIZED} 

356 return False 

357 

358 

359def validate_transition(previous: OrderStatus, current: OrderStatus) -> None: 

360 """Raise when an order attempts a lifecycle transition the broker cannot make.""" 

361 previous = OrderStatus(previous) 

362 current = OrderStatus(current) 

363 if not is_valid_transition(previous, current): 

364 raise ValueError(f"Illegal order status transition: {previous.value} -> {current.value}")