pytest-state-guard 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,4 @@
1
+ """pytest-state-guard: ThreadPoolExecutor task lifetime auditor for pytest."""
2
+
3
+ __version__ = "0.1.0"
4
+ __all__ = ["__version__"]
@@ -0,0 +1,208 @@
1
+ from __future__ import annotations
2
+
3
+ import threading
4
+ import uuid
5
+ from concurrent.futures import Future, ThreadPoolExecutor
6
+ from typing import Any, Callable
7
+
8
+ from pytest_state_guard.ledger import Ledger
9
+ from pytest_state_guard.models import CallableState, FutureState
10
+ from pytest_state_guard.owners import (
11
+ OwnerContext,
12
+ execution_context,
13
+ get_current_owner,
14
+ get_current_task_id,
15
+ )
16
+
17
+ _PATCH_LOCK = threading.Lock()
18
+ _REAL_ORIGINAL_SUBMIT: Callable[..., Any] = ThreadPoolExecutor.submit
19
+ _ACTIVE_LEDGER: Ledger | None = None
20
+ _IS_PATCHED = False
21
+
22
+
23
+ def _safe_exception_metadata(exc: BaseException) -> tuple[str, str | None]:
24
+ """Safely extract exception type and message without risking user __str__() failures."""
25
+ exc_type = type(exc).__qualname__
26
+ try:
27
+ msg = str(exc)
28
+ exc_msg = msg if type(msg) is str else None
29
+ except BaseException:
30
+ exc_msg = "<exception formatting raised>"
31
+ return exc_type, exc_msg
32
+
33
+
34
+ class _CallableWrapper:
35
+ """Wraps user callable to track execution lifecycle and establish worker context."""
36
+
37
+ def __init__(
38
+ self,
39
+ fn: Callable[..., Any],
40
+ task_id: str,
41
+ owner: OwnerContext,
42
+ ledger: Ledger,
43
+ ) -> None:
44
+ self._fn = fn
45
+ self._task_id = task_id
46
+ self._owner = owner
47
+ self._ledger = ledger
48
+
49
+ def __call__(self, *args: Any, **kwargs: Any) -> Any:
50
+ with execution_context(self._owner, self._task_id):
51
+ try:
52
+ self._ledger.commit_callable_started(self._task_id)
53
+ except Exception:
54
+ # Fail-open: do not prevent user work from executing
55
+ pass
56
+
57
+ outcome = CallableState.EXITED_RETURNED
58
+ exc_type: str | None = None
59
+ exc_msg: str | None = None
60
+
61
+ try:
62
+ return self._fn(*args, **kwargs)
63
+ except BaseException as exc:
64
+ outcome = CallableState.EXITED_RAISED
65
+ exc_type, exc_msg = _safe_exception_metadata(exc)
66
+ raise
67
+ finally:
68
+ try:
69
+ self._ledger.commit_callable_exited(
70
+ self._task_id,
71
+ outcome=outcome,
72
+ exception_type=exc_type,
73
+ exception_message=exc_msg,
74
+ )
75
+ except Exception:
76
+ # Do not let instrumentation error mask in-flight user exception
77
+ pass
78
+
79
+
80
+ class _FutureCallback:
81
+ """Callback attached to Future to observe settlement."""
82
+
83
+ def __init__(self, task_id: str, ledger: Ledger) -> None:
84
+ self._task_id = task_id
85
+ self._ledger = ledger
86
+
87
+ def __call__(self, future: Future[Any]) -> None:
88
+ try:
89
+ if future.cancelled():
90
+ terminal_state = FutureState.CANCELLED
91
+ else:
92
+ terminal_state = FutureState.FINISHED
93
+ self._ledger.commit_future_done(self._task_id, terminal_state)
94
+ except Exception:
95
+ # Future callback exceptions are isolated; do not affect user Future status
96
+ pass
97
+
98
+
99
+ def _state_guard_submit(
100
+ self: ThreadPoolExecutor,
101
+ fn: Callable[..., Any],
102
+ *args: Any,
103
+ **kwargs: Any,
104
+ ) -> Future[Any]:
105
+ """Intercepts ThreadPoolExecutor.submit to track task lifecycles under active owners."""
106
+ ledger = _ACTIVE_LEDGER
107
+ owner = get_current_owner()
108
+
109
+ # Unowned submission or inactive ledger: minimal overhead direct pass-through
110
+ if ledger is None or owner is None:
111
+ return _REAL_ORIGINAL_SUBMIT(self, fn, *args, **kwargs)
112
+
113
+ # Generate collision-resistant full UUID task ID
114
+ task_id = f"task:{uuid.uuid4().hex}"
115
+ parent_task_id = get_current_task_id()
116
+
117
+ # Step 1: Pre-submission reservation
118
+ try:
119
+ ledger.reserve_task(task_id, owner.owner_id, parent_task_id=parent_task_id)
120
+ except Exception:
121
+ # Fail-open: execute uninstrumented rather than breaking user submission
122
+ return _REAL_ORIGINAL_SUBMIT(self, fn, *args, **kwargs)
123
+
124
+ # Step 2: Wrap user callable
125
+ wrapped_fn = _CallableWrapper(fn, task_id, owner, ledger)
126
+
127
+ # Step 3: Invoke original submit
128
+ try:
129
+ future = _REAL_ORIGINAL_SUBMIT(self, wrapped_fn, *args, **kwargs)
130
+ except BaseException as submit_exc:
131
+ exc_type, exc_msg = _safe_exception_metadata(submit_exc)
132
+ try:
133
+ ledger.commit_submit_raised(
134
+ task_id,
135
+ exception_type=exc_type,
136
+ exception_message=exc_msg,
137
+ )
138
+ except Exception:
139
+ pass
140
+ raise # Re-raise original exception unchanged
141
+
142
+ # Step 4: Record submit returned
143
+ try:
144
+ ledger.commit_submit_returned(task_id)
145
+ except Exception:
146
+ pass
147
+
148
+ # Step 5: Attach done callback
149
+ try:
150
+ future.add_done_callback(_FutureCallback(task_id, ledger))
151
+ except Exception:
152
+ pass
153
+
154
+ return future
155
+
156
+
157
+ def install_patch(ledger: Ledger) -> None:
158
+ """Install ThreadPoolExecutor.submit monkeypatch.
159
+
160
+ Thread-safe and idempotent for the same ledger.
161
+ Raises RuntimeError if already patched with a different ledger.
162
+ """
163
+ global _ACTIVE_LEDGER, _IS_PATCHED
164
+
165
+ with _PATCH_LOCK:
166
+ if _IS_PATCHED:
167
+ if _ACTIVE_LEDGER is ledger:
168
+ return
169
+ raise RuntimeError(
170
+ "State Guard ThreadPoolExecutor patch is already active with a different ledger"
171
+ )
172
+
173
+ ThreadPoolExecutor.submit = _state_guard_submit # type: ignore[method-assign]
174
+ _ACTIVE_LEDGER = ledger
175
+ _IS_PATCHED = True
176
+
177
+
178
+ def remove_patch() -> None:
179
+ """Restore original ThreadPoolExecutor.submit.
180
+
181
+ Safely handles foreign wrappers: if ThreadPoolExecutor.submit was wrapped
182
+ by another library after State Guard, leaves the pointer untouched and
183
+ disables interception via _ACTIVE_LEDGER = None.
184
+ """
185
+ global _ACTIVE_LEDGER, _IS_PATCHED
186
+
187
+ with _PATCH_LOCK:
188
+ if not _IS_PATCHED:
189
+ return
190
+
191
+ # Check if our wrapper is still the top-level method
192
+ if getattr(ThreadPoolExecutor, "submit", None) is _state_guard_submit:
193
+ ThreadPoolExecutor.submit = _REAL_ORIGINAL_SUBMIT # type: ignore[method-assign]
194
+
195
+ _ACTIVE_LEDGER = None
196
+ _IS_PATCHED = False
197
+
198
+
199
+ def is_patched() -> bool:
200
+ """Return True if State Guard patch is currently active."""
201
+ with _PATCH_LOCK:
202
+ return _IS_PATCHED
203
+
204
+
205
+ def get_active_ledger() -> Ledger | None:
206
+ """Return the active ledger associated with the current patch, if any."""
207
+ with _PATCH_LOCK:
208
+ return _ACTIVE_LEDGER
@@ -0,0 +1,413 @@
1
+ from __future__ import annotations
2
+
3
+ import dataclasses
4
+ import itertools
5
+ import threading
6
+ import time
7
+ from typing import Any, Mapping
8
+
9
+ from pytest_state_guard.models import (
10
+ CallableState,
11
+ DuplicateEntityError,
12
+ EntityNotFoundError,
13
+ EventRecord,
14
+ EventType,
15
+ FutureState,
16
+ InvalidTransitionError,
17
+ OwnerRecord,
18
+ OwnerState,
19
+ OwnerType,
20
+ SubmissionState,
21
+ TaskRecord,
22
+ )
23
+
24
+
25
+ class Ledger:
26
+ """Thread-safe synchronized event ledger.
27
+
28
+ Serializes all lifecycle commits under a single non-reentrant lock.
29
+ Maintains an append-only event history alongside immutable point-in-time
30
+ owner and task records.
31
+ """
32
+
33
+ def __init__(self) -> None:
34
+ self._lock = threading.Lock()
35
+ self._seq_counter = itertools.count(1)
36
+ self._events: list[EventRecord] = []
37
+ self._owners: dict[str, OwnerRecord] = {}
38
+ self._tasks: dict[str, TaskRecord] = {}
39
+
40
+ # -----------------------------------------------------------------------
41
+ # Internal Locked Helpers
42
+ # -----------------------------------------------------------------------
43
+
44
+ def _commit_event_locked(
45
+ self,
46
+ event_type: EventType,
47
+ owner_id: str,
48
+ task_id: str | None = None,
49
+ details: Mapping[str, Any] | None = None,
50
+ ) -> EventRecord:
51
+ """Allocate seq_id and timestamp, append to history, and return event.
52
+
53
+ MUST be invoked while holding self._lock.
54
+ """
55
+ ts_ns = time.monotonic_ns()
56
+ seq_id = next(self._seq_counter)
57
+ thread_id = threading.get_ident()
58
+
59
+ event = EventRecord(
60
+ seq_id=seq_id,
61
+ ts_ns=ts_ns,
62
+ event_type=event_type,
63
+ owner_id=owner_id,
64
+ task_id=task_id,
65
+ thread_id=thread_id,
66
+ details=details,
67
+ )
68
+ self._events.append(event)
69
+ return event
70
+
71
+ # -----------------------------------------------------------------------
72
+ # Owner Lifecycle Commits
73
+ # -----------------------------------------------------------------------
74
+
75
+ def create_owner(
76
+ self,
77
+ owner_id: str,
78
+ owner_type: OwnerType,
79
+ nodeid: str,
80
+ fixture_name: str | None = None,
81
+ ) -> OwnerRecord:
82
+ """Register a new active owner."""
83
+ with self._lock:
84
+ if owner_id in self._owners:
85
+ raise DuplicateEntityError(f"Owner '{owner_id}' already exists")
86
+
87
+ ev = self._commit_event_locked(
88
+ event_type=EventType.OWNER_CREATED,
89
+ owner_id=owner_id,
90
+ details={"owner_type": owner_type.value, "nodeid": nodeid},
91
+ )
92
+ owner = OwnerRecord(
93
+ owner_id=owner_id,
94
+ owner_type=owner_type,
95
+ nodeid=nodeid,
96
+ created_seq=ev.seq_id,
97
+ state=OwnerState.ACTIVE,
98
+ fixture_name=fixture_name,
99
+ )
100
+ self._owners[owner_id] = owner
101
+ return owner
102
+
103
+ def finalize_owner(self, owner_id: str) -> OwnerRecord:
104
+ """Commit owner finalization (irreversible one-way transition)."""
105
+ with self._lock:
106
+ if owner_id not in self._owners:
107
+ raise EntityNotFoundError(f"Owner '{owner_id}' not found")
108
+
109
+ current = self._owners[owner_id]
110
+ if current.state == OwnerState.FINALIZED:
111
+ raise InvalidTransitionError(
112
+ f"Owner '{owner_id}' is already finalized at seq {current.finalized_seq}"
113
+ )
114
+
115
+ ev = self._commit_event_locked(
116
+ event_type=EventType.OWNER_FINALIZED,
117
+ owner_id=owner_id,
118
+ )
119
+ updated = dataclasses.replace(
120
+ current,
121
+ state=OwnerState.FINALIZED,
122
+ finalized_seq=ev.seq_id,
123
+ )
124
+ self._owners[owner_id] = updated
125
+ return updated
126
+
127
+ # -----------------------------------------------------------------------
128
+ # Task Lifecycle Commits
129
+ # -----------------------------------------------------------------------
130
+
131
+ def reserve_task(
132
+ self,
133
+ task_id: str,
134
+ owner_id: str,
135
+ parent_task_id: str | None = None,
136
+ ) -> TaskRecord:
137
+ """Reserve a task identity under an active owner prior to submit()."""
138
+ with self._lock:
139
+ if task_id in self._tasks:
140
+ raise DuplicateEntityError(f"Task '{task_id}' already exists")
141
+ if owner_id not in self._owners:
142
+ raise EntityNotFoundError(f"Owner '{owner_id}' not found")
143
+ if parent_task_id is not None and parent_task_id not in self._tasks:
144
+ raise EntityNotFoundError(f"Parent task '{parent_task_id}' not found")
145
+
146
+ ev = self._commit_event_locked(
147
+ event_type=EventType.TASK_RESERVED,
148
+ owner_id=owner_id,
149
+ task_id=task_id,
150
+ details={"parent_task_id": parent_task_id},
151
+ )
152
+ task = TaskRecord(
153
+ task_id=task_id,
154
+ owner_id=owner_id,
155
+ created_seq=ev.seq_id,
156
+ submission_state=SubmissionState.RESERVED,
157
+ callable_state=CallableState.NOT_STARTED,
158
+ future_state=FutureState.UNKNOWN,
159
+ parent_task_id=parent_task_id,
160
+ )
161
+ self._tasks[task_id] = task
162
+ return task
163
+
164
+ def commit_submit_returned(self, task_id: str) -> TaskRecord:
165
+ """Commit successful return of ThreadPoolExecutor.submit()."""
166
+ with self._lock:
167
+ if task_id not in self._tasks:
168
+ raise EntityNotFoundError(f"Task '{task_id}' not found")
169
+
170
+ current = self._tasks[task_id]
171
+ if current.submission_state != SubmissionState.RESERVED:
172
+ raise InvalidTransitionError(
173
+ f"Cannot commit SUBMIT_RETURNED from submission state '{current.submission_state}'"
174
+ )
175
+
176
+ ev = self._commit_event_locked(
177
+ event_type=EventType.SUBMIT_RETURNED,
178
+ owner_id=current.owner_id,
179
+ task_id=task_id,
180
+ )
181
+ new_future_state = (
182
+ FutureState.PENDING
183
+ if current.future_state == FutureState.UNKNOWN
184
+ else current.future_state
185
+ )
186
+ updated = dataclasses.replace(
187
+ current,
188
+ submission_state=SubmissionState.SUBMIT_RETURNED,
189
+ future_state=new_future_state,
190
+ )
191
+ self._tasks[task_id] = updated
192
+ return updated
193
+
194
+ def commit_submit_raised(
195
+ self,
196
+ task_id: str,
197
+ exception_type: str | None = None,
198
+ exception_message: str | None = None,
199
+ ) -> TaskRecord:
200
+ """Commit that ThreadPoolExecutor.submit() raised an exception.
201
+
202
+ Transition is to SUBMIT_RAISED_UNVERIFIED because CPython may have enqueued
203
+ the work item before failing to adjust the worker thread count.
204
+ """
205
+ with self._lock:
206
+ if task_id not in self._tasks:
207
+ raise EntityNotFoundError(f"Task '{task_id}' not found")
208
+
209
+ current = self._tasks[task_id]
210
+ if current.submission_state != SubmissionState.RESERVED:
211
+ raise InvalidTransitionError(
212
+ f"Cannot commit SUBMIT_RAISED from submission state '{current.submission_state}'"
213
+ )
214
+
215
+ ev = self._commit_event_locked(
216
+ event_type=EventType.SUBMIT_RAISED,
217
+ owner_id=current.owner_id,
218
+ task_id=task_id,
219
+ details={"exception_type": exception_type},
220
+ )
221
+ updated = dataclasses.replace(
222
+ current,
223
+ submission_state=SubmissionState.SUBMIT_RAISED_UNVERIFIED,
224
+ exception_type=exception_type,
225
+ exception_message=exception_message,
226
+ )
227
+ self._tasks[task_id] = updated
228
+ return updated
229
+
230
+ def commit_callable_started(self, task_id: str) -> TaskRecord:
231
+ """Commit that the wrapped callable began execution."""
232
+ with self._lock:
233
+ if task_id not in self._tasks:
234
+ raise EntityNotFoundError(f"Task '{task_id}' not found")
235
+
236
+ current = self._tasks[task_id]
237
+ if current.callable_state != CallableState.NOT_STARTED:
238
+ raise InvalidTransitionError(
239
+ f"Cannot start callable from state '{current.callable_state}'"
240
+ )
241
+
242
+ ev = self._commit_event_locked(
243
+ event_type=EventType.CALLABLE_STARTED,
244
+ owner_id=current.owner_id,
245
+ task_id=task_id,
246
+ )
247
+ # If submit raised but callable executes, record anomaly event
248
+ if current.submission_state == SubmissionState.SUBMIT_RAISED_UNVERIFIED:
249
+ self._commit_event_locked(
250
+ event_type=EventType.EXECUTION_WITHOUT_RETURNED_FUTURE,
251
+ owner_id=current.owner_id,
252
+ task_id=task_id,
253
+ )
254
+
255
+ updated = dataclasses.replace(
256
+ current,
257
+ callable_state=CallableState.RUNNING,
258
+ )
259
+ self._tasks[task_id] = updated
260
+ return updated
261
+
262
+ def commit_callable_exited(
263
+ self,
264
+ task_id: str,
265
+ outcome: CallableState,
266
+ exception_type: str | None = None,
267
+ exception_message: str | None = None,
268
+ ) -> TaskRecord:
269
+ """Commit that the wrapped callable exited (returned or raised)."""
270
+ with self._lock:
271
+ if task_id not in self._tasks:
272
+ raise EntityNotFoundError(f"Task '{task_id}' not found")
273
+
274
+ current = self._tasks[task_id]
275
+ if outcome not in (CallableState.EXITED_RETURNED, CallableState.EXITED_RAISED):
276
+ raise InvalidTransitionError(
277
+ f"Invalid callable exit outcome '{outcome}'; expected EXITED_RETURNED or EXITED_RAISED"
278
+ )
279
+ if current.callable_state != CallableState.RUNNING:
280
+ raise InvalidTransitionError(
281
+ f"Cannot exit callable from state '{current.callable_state}'"
282
+ )
283
+
284
+ ev = self._commit_event_locked(
285
+ event_type=EventType.CALLABLE_EXITED,
286
+ owner_id=current.owner_id,
287
+ task_id=task_id,
288
+ details={"outcome": outcome.value, "exception_type": exception_type},
289
+ )
290
+ updated = dataclasses.replace(
291
+ current,
292
+ callable_state=outcome,
293
+ exception_type=exception_type or current.exception_type,
294
+ exception_message=exception_message or current.exception_message,
295
+ )
296
+ self._tasks[task_id] = updated
297
+ return updated
298
+
299
+ def commit_future_done(
300
+ self,
301
+ task_id: str,
302
+ terminal_state: FutureState,
303
+ ) -> TaskRecord:
304
+ """Commit observation of Future done callback."""
305
+ with self._lock:
306
+ if task_id not in self._tasks:
307
+ raise EntityNotFoundError(f"Task '{task_id}' not found")
308
+
309
+ current = self._tasks[task_id]
310
+ if terminal_state not in (FutureState.FINISHED, FutureState.CANCELLED):
311
+ raise InvalidTransitionError(
312
+ f"Terminal future state must be FINISHED or CANCELLED, got '{terminal_state}'"
313
+ )
314
+ if current.future_state in (FutureState.FINISHED, FutureState.CANCELLED):
315
+ raise InvalidTransitionError(
316
+ f"Task '{task_id}' future is already in terminal state '{current.future_state.value}'; "
317
+ f"cannot transition to '{terminal_state.value}'"
318
+ )
319
+
320
+ ev = self._commit_event_locked(
321
+ event_type=EventType.FUTURE_DONE_CALLBACK_OBSERVED,
322
+ owner_id=current.owner_id,
323
+ task_id=task_id,
324
+ details={"terminal_state": terminal_state.value},
325
+ )
326
+ updated = dataclasses.replace(
327
+ current,
328
+ future_state=terminal_state,
329
+ )
330
+ self._tasks[task_id] = updated
331
+ return updated
332
+
333
+ # -----------------------------------------------------------------------
334
+ # Snapshots and Queries
335
+ # -----------------------------------------------------------------------
336
+
337
+ def get_owner(self, owner_id: str) -> OwnerRecord:
338
+ """Retrieve an immutable snapshot of an owner record."""
339
+ with self._lock:
340
+ if owner_id not in self._owners:
341
+ raise EntityNotFoundError(f"Owner '{owner_id}' not found")
342
+ return self._owners[owner_id]
343
+
344
+ def get_task(self, task_id: str) -> TaskRecord:
345
+ """Retrieve an immutable snapshot of a task record."""
346
+ with self._lock:
347
+ if task_id not in self._tasks:
348
+ raise EntityNotFoundError(f"Task '{task_id}' not found")
349
+ return self._tasks[task_id]
350
+
351
+ def get_all_owners(self) -> list[OwnerRecord]:
352
+ """Return a snapshot list of all owner records."""
353
+ with self._lock:
354
+ return list(self._owners.values())
355
+
356
+ def get_all_tasks(self) -> list[TaskRecord]:
357
+ """Return a snapshot list of all task records."""
358
+ with self._lock:
359
+ return list(self._tasks.values())
360
+
361
+ def get_tasks_for_owner(self, owner_id: str) -> list[TaskRecord]:
362
+ """Return a snapshot list of tasks associated with an owner."""
363
+ with self._lock:
364
+ return [t for t in self._tasks.values() if t.owner_id == owner_id]
365
+
366
+ def get_events(self) -> list[EventRecord]:
367
+ """Return an immutable point-in-time snapshot of the event history."""
368
+ with self._lock:
369
+ return list(self._events)
370
+
371
+ def get_events_for_owner(self, owner_id: str) -> list[EventRecord]:
372
+ """Return events relevant to a specific owner."""
373
+ with self._lock:
374
+ return [e for e in self._events if e.owner_id == owner_id]
375
+
376
+ def get_events_for_task(self, task_id: str) -> list[EventRecord]:
377
+ """Return events relevant to a specific task."""
378
+ with self._lock:
379
+ return [e for e in self._events if e.task_id == task_id]
380
+
381
+ def get_owner_snapshot(
382
+ self, owner_id: str
383
+ ) -> tuple[OwnerRecord, list[TaskRecord], list[EventRecord]]:
384
+ """Return a single coherent atomic point-in-time snapshot of an owner, its tasks, and its events.
385
+
386
+ All three collections are captured under a single acquisition of the ledger lock,
387
+ guaranteeing that task and event records correspond to the exact same sequence point.
388
+ The returned lists are freshly copied collections containing immutable records.
389
+ """
390
+ with self._lock:
391
+ if owner_id not in self._owners:
392
+ raise EntityNotFoundError(f"Owner '{owner_id}' not found")
393
+ owner = self._owners[owner_id]
394
+ tasks = [t for t in self._tasks.values() if t.owner_id == owner_id]
395
+ events = [e for e in self._events if e.owner_id == owner_id]
396
+ return owner, list(tasks), list(events)
397
+
398
+ def get_finalized_session_snapshot(
399
+ self,
400
+ ) -> tuple[list[OwnerRecord], list[TaskRecord], list[EventRecord]]:
401
+ """Return a single coherent atomic point-in-time snapshot of all finalized owners, tasks, and events.
402
+
403
+ All records are captured under a single acquisition of the ledger lock,
404
+ guaranteeing process-wide consistency across all owners and tasks at that sequence point.
405
+ The returned lists are freshly copied collections containing immutable records.
406
+ """
407
+ with self._lock:
408
+ finalized_owners = [
409
+ o for o in self._owners.values() if o.state == OwnerState.FINALIZED
410
+ ]
411
+ tasks = list(self._tasks.values())
412
+ events = list(self._events)
413
+ return list(finalized_owners), list(tasks), list(events)