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
« 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."""
3from enum import StrEnum
6class OrderStatus(StrEnum):
7 """Local intent and Alpaca order states understood by the executor."""
9 PREPARED = "prepared"
10 UNCERTAIN = "uncertain"
11 ABORTED_BEFORE_SUBMIT = "aborted_before_submit"
12 RELEASED_UNSUBMITTED = "released_unsubmitted"
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"
26 FILLED = "filled"
27 CANCELED = "canceled"
28 EXPIRED = "expired"
29 REPLACED = "replaced"
30 REJECTED = "rejected"
31 CALCULATED = "calculated"
32 UNRECOGNIZED = "unrecognized"
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)
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)
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)
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)
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}
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
318def is_pending(status: OrderStatus) -> bool:
319 return OrderStatus(status) in _PENDING
322def is_terminal(status: OrderStatus) -> bool:
323 return OrderStatus(status) in _TERMINAL
326def is_cancelable(status: OrderStatus) -> bool:
327 return OrderStatus(status) in _CANCELABLE
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
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}")