clutterxp 1.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.
Files changed (84) hide show
  1. clutterxp/__init__.py +4 -0
  2. clutterxp/cli/__init__.py +7 -0
  3. clutterxp/cli/app.py +251 -0
  4. clutterxp/cli/cmd_config.py +250 -0
  5. clutterxp/cli/cmd_doctor.py +449 -0
  6. clutterxp/cli/cmd_duplicates.py +253 -0
  7. clutterxp/cli/cmd_gui.py +22 -0
  8. clutterxp/cli/cmd_history.py +233 -0
  9. clutterxp/cli/cmd_init.py +76 -0
  10. clutterxp/cli/cmd_organize.py +226 -0
  11. clutterxp/cli/cmd_rules.py +540 -0
  12. clutterxp/cli/cmd_scan.py +109 -0
  13. clutterxp/cli/cmd_service.py +130 -0
  14. clutterxp/cli/cmd_undo.py +180 -0
  15. clutterxp/cli/cmd_watch.py +147 -0
  16. clutterxp/cli/errors.py +166 -0
  17. clutterxp/cli/render.py +390 -0
  18. clutterxp/config/__init__.py +40 -0
  19. clutterxp/config/jsonschema.py +12 -0
  20. clutterxp/config/loader.py +212 -0
  21. clutterxp/config/placeholders.py +79 -0
  22. clutterxp/config/runtime.py +30 -0
  23. clutterxp/config/schema.py +166 -0
  24. clutterxp/config/validate.py +226 -0
  25. clutterxp/config/writer.py +248 -0
  26. clutterxp/config.example.yaml +76 -0
  27. clutterxp/duplicates/__init__.py +22 -0
  28. clutterxp/duplicates/detector.py +438 -0
  29. clutterxp/duplicates/hashcache.py +149 -0
  30. clutterxp/duplicates/namenorm.py +45 -0
  31. clutterxp/duplicates/quarantine.py +196 -0
  32. clutterxp/duplicates/report.py +110 -0
  33. clutterxp/gui/__init__.py +1 -0
  34. clutterxp/gui/api.py +494 -0
  35. clutterxp/gui/app.py +205 -0
  36. clutterxp/gui/models_qt.py +544 -0
  37. clutterxp/gui/views/__init__.py +21 -0
  38. clutterxp/gui/views/dashboard.py +253 -0
  39. clutterxp/gui/views/duplicates.py +404 -0
  40. clutterxp/gui/views/folders.py +354 -0
  41. clutterxp/gui/views/history.py +281 -0
  42. clutterxp/gui/views/preview.py +277 -0
  43. clutterxp/gui/views/rules.py +527 -0
  44. clutterxp/gui/views/settings.py +172 -0
  45. clutterxp/gui/workers.py +147 -0
  46. clutterxp/history/__init__.py +23 -0
  47. clutterxp/history/db.py +174 -0
  48. clutterxp/history/pathcodec.py +42 -0
  49. clutterxp/history/recovery.py +318 -0
  50. clutterxp/history/schema.sql +43 -0
  51. clutterxp/history/service.py +493 -0
  52. clutterxp/history/undo.py +373 -0
  53. clutterxp/interfaces.py +164 -0
  54. clutterxp/locking.py +113 -0
  55. clutterxp/logging_setup.py +73 -0
  56. clutterxp/models.py +266 -0
  57. clutterxp/mover/__init__.py +26 -0
  58. clutterxp/mover/collision.py +46 -0
  59. clutterxp/mover/fsops.py +191 -0
  60. clutterxp/mover/safe_move.py +741 -0
  61. clutterxp/organizer.py +388 -0
  62. clutterxp/packaging/clutterxp.service +15 -0
  63. clutterxp/paths.py +112 -0
  64. clutterxp/planner.py +339 -0
  65. clutterxp/py.typed +0 -0
  66. clutterxp/rules/__init__.py +16 -0
  67. clutterxp/rules/engine.py +374 -0
  68. clutterxp/rules/matcher.py +222 -0
  69. clutterxp/rules/template.py +171 -0
  70. clutterxp/rules/tokenizer.py +118 -0
  71. clutterxp/safety.py +111 -0
  72. clutterxp/scanner.py +196 -0
  73. clutterxp/service_install.py +208 -0
  74. clutterxp/units.py +59 -0
  75. clutterxp/watch/__init__.py +37 -0
  76. clutterxp/watch/debounce.py +84 -0
  77. clutterxp/watch/events.py +259 -0
  78. clutterxp/watch/ignore.py +77 -0
  79. clutterxp/watch/service.py +662 -0
  80. clutterxp/watch/settle.py +170 -0
  81. clutterxp-1.1.0.dist-info/METADATA +149 -0
  82. clutterxp-1.1.0.dist-info/RECORD +84 -0
  83. clutterxp-1.1.0.dist-info/WHEEL +4 -0
  84. clutterxp-1.1.0.dist-info/entry_points.txt +6 -0
@@ -0,0 +1,43 @@
1
+ CREATE TABLE batches (
2
+ id INTEGER PRIMARY KEY,
3
+ created_at TEXT NOT NULL,
4
+ command TEXT NOT NULL,
5
+ folder TEXT,
6
+ note TEXT
7
+ );
8
+
9
+ CREATE TABLE operations (
10
+ id INTEGER PRIMARY KEY,
11
+ batch_id INTEGER NOT NULL REFERENCES batches(id) ON DELETE CASCADE,
12
+ status TEXT NOT NULL CHECK (status IN ('pending','done','undone','failed','skipped')),
13
+ src_path TEXT NOT NULL,
14
+ dst_path TEXT,
15
+ rule_name TEXT,
16
+ strategy TEXT,
17
+ size INTEGER,
18
+ mtime_ns INTEGER,
19
+ inode INTEGER,
20
+ device INTEGER,
21
+ sha256 TEXT,
22
+ created_dirs TEXT, -- JSON array
23
+ created_at TEXT NOT NULL,
24
+ finished_at TEXT,
25
+ undone_at TEXT,
26
+ error TEXT
27
+ );
28
+ CREATE INDEX idx_ops_batch ON operations(batch_id);
29
+ CREATE INDEX idx_ops_status ON operations(status);
30
+ CREATE INDEX idx_ops_dst ON operations(dst_path);
31
+ CREATE INDEX idx_ops_rule ON operations(rule_name);
32
+
33
+ CREATE TABLE events (
34
+ id INTEGER PRIMARY KEY,
35
+ ts TEXT NOT NULL,
36
+ level TEXT NOT NULL,
37
+ kind TEXT NOT NULL,
38
+ batch_id INTEGER,
39
+ op_id INTEGER,
40
+ path TEXT,
41
+ message TEXT NOT NULL
42
+ );
43
+ CREATE INDEX idx_events_ts ON events(ts);
@@ -0,0 +1,493 @@
1
+ """History service: journal-first operations, queries, prune, and events."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import contextlib
6
+ import json
7
+ import sqlite3
8
+ import threading
9
+ import time
10
+ from collections.abc import Callable, Generator, Sequence
11
+ from datetime import datetime, timedelta, timezone
12
+ from pathlib import Path
13
+ from typing import Any
14
+
15
+ from clutterxp.history import pathcodec
16
+ from clutterxp.history.db import connect
17
+ from clutterxp.models import (
18
+ FileInfo,
19
+ MoveResult,
20
+ MoveStrategy,
21
+ OperationRecord,
22
+ OpStatus,
23
+ )
24
+ from clutterxp.units import parse_duration_seconds
25
+
26
+
27
+ def _default_clock() -> str:
28
+ """Return current UTC time formatted as ISO-8601 string."""
29
+ return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
30
+
31
+
32
+ def _parse_iso(s: str) -> datetime:
33
+ """Parse ISO-8601 string into datetime in UTC."""
34
+ normalized = s.replace("Z", "+00:00")
35
+ try:
36
+ dt = datetime.fromisoformat(normalized)
37
+ if dt.tzinfo is None:
38
+ return dt.replace(tzinfo=timezone.utc)
39
+ return dt.astimezone(timezone.utc)
40
+ except ValueError:
41
+ return datetime.now(timezone.utc)
42
+
43
+
44
+ @contextlib.contextmanager
45
+ def _write_tx(conn: sqlite3.Connection, max_retries: int = 30) -> Generator[None, None, None]:
46
+ """Context manager for immediate write transactions with automatic backoff retry on locks."""
47
+ for attempt in range(max_retries):
48
+ try:
49
+ conn.execute("BEGIN IMMEDIATE;")
50
+ break
51
+ except sqlite3.OperationalError as e:
52
+ is_locked = "locked" in str(e).lower() or "busy" in str(e).lower()
53
+ if is_locked and attempt < max_retries - 1:
54
+ time.sleep(0.01 * (attempt + 1))
55
+ else:
56
+ raise
57
+ try:
58
+ yield
59
+ for attempt in range(max_retries):
60
+ try:
61
+ conn.execute("COMMIT;")
62
+ break
63
+ except sqlite3.OperationalError as e:
64
+ is_locked = "locked" in str(e).lower() or "busy" in str(e).lower()
65
+ if is_locked and attempt < max_retries - 1:
66
+ time.sleep(0.01 * (attempt + 1))
67
+ else:
68
+ raise
69
+ except Exception:
70
+ with contextlib.suppress(Exception):
71
+ conn.execute("ROLLBACK;")
72
+ raise
73
+
74
+
75
+ def op_to_dict(op: OperationRecord) -> dict[str, Any]:
76
+ """Convert an OperationRecord into a JSON-serializable dictionary."""
77
+ return {
78
+ "id": op.id,
79
+ "batch_id": op.batch_id,
80
+ "status": op.status.value,
81
+ "src_path": str(op.src_path),
82
+ "dst_path": str(op.dst_path) if op.dst_path is not None else None,
83
+ "rule_name": op.rule_name,
84
+ "strategy": op.strategy.value if op.strategy is not None else None,
85
+ "size": op.size,
86
+ "mtime_ns": op.mtime_ns,
87
+ "inode": op.inode,
88
+ "device": op.device,
89
+ "sha256": op.sha256,
90
+ "created_dirs": [str(p) for p in op.created_dirs],
91
+ "created_at": op.created_at,
92
+ "finished_at": op.finished_at,
93
+ "undone_at": op.undone_at,
94
+ "error": op.error,
95
+ }
96
+
97
+
98
+ class HistoryService:
99
+ """SQLite-backed implementation of the History Protocol.
100
+
101
+ Enforces journal-first durability (S5), per-thread database connections,
102
+ comprehensive filtering queries, event logging, and safe pruning.
103
+ """
104
+
105
+ def __init__(
106
+ self,
107
+ db_path: Path,
108
+ *,
109
+ clock: Callable[[], str] | None = None,
110
+ ) -> None:
111
+ """Initialize HistoryService with database path and optional clock.
112
+
113
+ Args:
114
+ db_path: Path to the SQLite history database file.
115
+ clock: Callable returning ISO-8601 UTC timestamp string. Defaults to current time.
116
+ """
117
+ self.db_path = Path(db_path)
118
+ self._clock: Callable[[], str] = clock if clock is not None else _default_clock
119
+ self._local = threading.local()
120
+
121
+ if str(self.db_path) != ":memory:":
122
+ init_conn = connect(self.db_path)
123
+ init_conn.close()
124
+
125
+ def now_iso(self) -> str:
126
+ """Return the current ISO-8601 UTC timestamp using the injected clock."""
127
+ return self._clock()
128
+
129
+ def _get_conn(self) -> sqlite3.Connection:
130
+ """Get or create a per-thread SQLite connection."""
131
+ conn = getattr(self._local, "conn", None)
132
+ if conn is None:
133
+ conn = connect(self.db_path)
134
+ self._local.conn = conn
135
+ return conn
136
+
137
+ def close(self) -> None:
138
+ """Close the connection associated with the current thread."""
139
+ conn = getattr(self._local, "conn", None)
140
+ if conn is not None:
141
+ conn.close()
142
+ self._local.conn = None
143
+
144
+ def begin_batch(
145
+ self,
146
+ command: str,
147
+ folder: Path | None = None,
148
+ note: str | None = None,
149
+ ) -> int:
150
+ """Insert a batch row and return the newly generated batch_id."""
151
+ conn = self._get_conn()
152
+ with _write_tx(conn):
153
+ folder_str = pathcodec.encode(folder) if folder is not None else None
154
+ cur = conn.execute(
155
+ """
156
+ INSERT INTO batches (created_at, command, folder, note)
157
+ VALUES (?, ?, ?, ?);
158
+ """,
159
+ (self.now_iso(), command, folder_str, note),
160
+ )
161
+ batch_id = cur.lastrowid
162
+ assert batch_id is not None
163
+ return batch_id
164
+
165
+ def get_batch(self, batch_id: int) -> dict[str, Any] | None:
166
+ """Retrieve batch metadata by batch_id."""
167
+ conn = self._get_conn()
168
+ cur = conn.execute("SELECT * FROM batches WHERE id = ?;", (batch_id,))
169
+ row = cur.fetchone()
170
+ if row is None:
171
+ return None
172
+ folder_raw = row["folder"]
173
+ return {
174
+ "id": int(row["id"]),
175
+ "created_at": str(row["created_at"]),
176
+ "command": str(row["command"]),
177
+ "folder": pathcodec.decode(folder_raw) if folder_raw is not None else None,
178
+ "note": row["note"],
179
+ }
180
+
181
+ def begin_op(
182
+ self,
183
+ batch_id: int,
184
+ src: Path,
185
+ rule_name: str | None,
186
+ file: FileInfo,
187
+ ) -> int:
188
+ """Insert status=pending BEFORE any filesystem change.
189
+
190
+ Must be committed and durable on return (journal-first per S5).
191
+ Returns op_id.
192
+ """
193
+ conn = self._get_conn()
194
+ with _write_tx(conn):
195
+ cur = conn.execute(
196
+ """
197
+ INSERT INTO operations (
198
+ batch_id, status, src_path, dst_path, rule_name, strategy,
199
+ size, mtime_ns, inode, device, sha256, created_dirs,
200
+ created_at, finished_at, undone_at, error
201
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?);
202
+ """,
203
+ (
204
+ batch_id,
205
+ OpStatus.PENDING.value,
206
+ pathcodec.encode(src),
207
+ None,
208
+ rule_name,
209
+ None,
210
+ file.size,
211
+ file.mtime_ns,
212
+ file.inode,
213
+ file.device,
214
+ None,
215
+ json.dumps([]),
216
+ self.now_iso(),
217
+ None,
218
+ None,
219
+ None,
220
+ ),
221
+ )
222
+ op_id = cur.lastrowid
223
+ assert op_id is not None
224
+ return op_id
225
+
226
+ def finish_op(self, op_id: int, result: MoveResult) -> None:
227
+ """Mark operation done or failed with final destination, strategy, and created dirs."""
228
+ conn = self._get_conn()
229
+ status = OpStatus.DONE.value if result.ok else OpStatus.FAILED.value
230
+ dst_str = pathcodec.encode(result.dst) if result.dst is not None else None
231
+ strat_str = result.strategy.value if result.strategy is not None else None
232
+ dirs_json = json.dumps([pathcodec.encode(p) for p in result.created_dirs])
233
+ error_str = None
234
+ if not result.ok:
235
+ error_str = result.message or (result.code.value if result.code else "failed")
236
+ now = self.now_iso()
237
+
238
+ with _write_tx(conn):
239
+ cur = conn.execute(
240
+ """
241
+ UPDATE operations
242
+ SET status = ?, dst_path = ?, strategy = ?, created_dirs = ?,
243
+ finished_at = ?, error = ?
244
+ WHERE id = ?;
245
+ """,
246
+ (status, dst_str, strat_str, dirs_json, now, error_str, op_id),
247
+ )
248
+ if cur.rowcount == 0:
249
+ msg = f"Operation id {op_id} not found"
250
+ raise KeyError(msg)
251
+
252
+ def record_event(
253
+ self,
254
+ kind: str,
255
+ message: str,
256
+ *,
257
+ level: str = "info",
258
+ batch_id: int | None = None,
259
+ op_id: int | None = None,
260
+ path: Path | None = None,
261
+ ) -> None:
262
+ """Insert an event log record."""
263
+ conn = self._get_conn()
264
+ path_str = pathcodec.encode(path) if path is not None else None
265
+ with _write_tx(conn):
266
+ conn.execute(
267
+ """
268
+ INSERT INTO events (ts, level, kind, batch_id, op_id, path, message)
269
+ VALUES (?, ?, ?, ?, ?, ?, ?);
270
+ """,
271
+ (self.now_iso(), level, kind, batch_id, op_id, path_str, message),
272
+ )
273
+
274
+ def _row_to_op(self, row: sqlite3.Row) -> OperationRecord:
275
+ """Convert a database row into a frozen OperationRecord dataclass."""
276
+ dst_raw = row["dst_path"]
277
+ strategy_raw = row["strategy"]
278
+ created_dirs_raw = row["created_dirs"]
279
+
280
+ created_dirs: tuple[Path, ...] = ()
281
+ if created_dirs_raw:
282
+ try:
283
+ parsed = json.loads(created_dirs_raw)
284
+ if isinstance(parsed, list):
285
+ created_dirs = tuple(pathcodec.decode(p) for p in parsed)
286
+ except Exception:
287
+ created_dirs = ()
288
+
289
+ return OperationRecord(
290
+ id=int(row["id"]),
291
+ batch_id=int(row["batch_id"]),
292
+ status=OpStatus(row["status"]),
293
+ src_path=pathcodec.decode(row["src_path"]),
294
+ dst_path=pathcodec.decode(dst_raw) if dst_raw is not None else None,
295
+ rule_name=row["rule_name"],
296
+ strategy=MoveStrategy(strategy_raw) if strategy_raw is not None else None,
297
+ size=int(row["size"]) if row["size"] is not None else None,
298
+ mtime_ns=int(row["mtime_ns"]) if row["mtime_ns"] is not None else None,
299
+ inode=int(row["inode"]) if row["inode"] is not None else None,
300
+ device=int(row["device"]) if row["device"] is not None else None,
301
+ sha256=row["sha256"],
302
+ created_dirs=created_dirs,
303
+ created_at=str(row["created_at"]),
304
+ finished_at=str(row["finished_at"]) if row["finished_at"] is not None else None,
305
+ undone_at=str(row["undone_at"]) if row["undone_at"] is not None else None,
306
+ error=str(row["error"]) if row["error"] is not None else None,
307
+ )
308
+
309
+ def get_op(self, op_id: int) -> OperationRecord | None:
310
+ """Retrieve an OperationRecord by op_id, or None if not found."""
311
+ conn = self._get_conn()
312
+ cur = conn.execute("SELECT * FROM operations WHERE id = ?;", (op_id,))
313
+ row = cur.fetchone()
314
+ if row is None:
315
+ return None
316
+ return self._row_to_op(row)
317
+
318
+ def _resolve_since(self, since_val: str) -> str:
319
+ """Resolve since_iso argument which may be a relative duration or ISO string."""
320
+ try:
321
+ secs = parse_duration_seconds(since_val)
322
+ base_dt = _parse_iso(self.now_iso())
323
+ cutoff_dt = base_dt - timedelta(seconds=secs)
324
+ return cutoff_dt.strftime("%Y-%m-%dT%H:%M:%SZ")
325
+ except ValueError:
326
+ return since_val
327
+
328
+ def list_ops(
329
+ self,
330
+ *,
331
+ batch_id: int | None = None,
332
+ status: OpStatus | None = None,
333
+ limit: int = 50,
334
+ since_iso: str | None = None,
335
+ rule_name: str | None = None,
336
+ path_contains: str | None = None,
337
+ order: str = "desc",
338
+ ) -> Sequence[OperationRecord]:
339
+ """List operations matching the specified filter criteria."""
340
+ clauses: list[str] = []
341
+ params: list[Any] = []
342
+
343
+ if batch_id is not None:
344
+ clauses.append("batch_id = ?")
345
+ params.append(batch_id)
346
+
347
+ if status is not None:
348
+ clauses.append("status = ?")
349
+ params.append(status.value)
350
+
351
+ if rule_name is not None:
352
+ clauses.append("rule_name = ?")
353
+ params.append(rule_name)
354
+
355
+ if since_iso is not None:
356
+ effective_since = self._resolve_since(since_iso)
357
+ clauses.append("created_at >= ?")
358
+ params.append(effective_since)
359
+
360
+ if path_contains is not None:
361
+ clauses.append("(src_path LIKE ? OR dst_path LIKE ?)")
362
+ pattern = f"%{path_contains}%"
363
+ params.extend([pattern, pattern])
364
+
365
+ order_sql = "ASC" if order.lower() == "asc" else "DESC"
366
+ where_sql = f"WHERE {' AND '.join(clauses)}" if clauses else ""
367
+ sql = f"SELECT * FROM operations {where_sql} ORDER BY id {order_sql} LIMIT ?;" # noqa: S608
368
+ params.append(limit)
369
+
370
+ conn = self._get_conn()
371
+ cur = conn.execute(sql, tuple(params))
372
+ return [self._row_to_op(row) for row in cur.fetchall()]
373
+
374
+ def last_batch_id(self, *, with_status: OpStatus = OpStatus.DONE) -> int | None:
375
+ """Find the highest batch_id that has at least one operation with with_status."""
376
+ conn = self._get_conn()
377
+ cur = conn.execute(
378
+ "SELECT MAX(batch_id) FROM operations WHERE status = ?;",
379
+ (with_status.value,),
380
+ )
381
+ row = cur.fetchone()
382
+ if row is None or row[0] is None:
383
+ return None
384
+ return int(row[0])
385
+
386
+ def mark_undone(self, op_id: int) -> None:
387
+ """Set status=undone and undone_at=now for the specified operation."""
388
+ conn = self._get_conn()
389
+ with _write_tx(conn):
390
+ cur = conn.execute(
391
+ "UPDATE operations SET status = ?, undone_at = ? WHERE id = ?;",
392
+ (OpStatus.UNDONE.value, self.now_iso(), op_id),
393
+ )
394
+ if cur.rowcount == 0:
395
+ msg = f"Operation id {op_id} not found"
396
+ raise KeyError(msg)
397
+
398
+ def pending_ops(self) -> Sequence[OperationRecord]:
399
+ """Return all operations currently in pending status, ordered by id ASC."""
400
+ conn = self._get_conn()
401
+ cur = conn.execute(
402
+ "SELECT * FROM operations WHERE status = ? ORDER BY id ASC;",
403
+ (OpStatus.PENDING.value,),
404
+ )
405
+ return [self._row_to_op(row) for row in cur.fetchall()]
406
+
407
+ def prune(self, older_than_days: int) -> int:
408
+ """Delete non-pending operations and events older than cutoff.
409
+
410
+ Empty batches are also removed. Never deletes operations with status='pending'.
411
+ Never deletes any user files on the filesystem.
412
+ Returns the number of operations deleted.
413
+ """
414
+ if older_than_days < 0:
415
+ msg = f"older_than_days must be non-negative: {older_than_days}"
416
+ raise ValueError(msg)
417
+
418
+ now_dt = _parse_iso(self.now_iso())
419
+ cutoff_dt = now_dt - timedelta(days=older_than_days)
420
+ cutoff_iso = cutoff_dt.strftime("%Y-%m-%dT%H:%M:%SZ")
421
+
422
+ conn = self._get_conn()
423
+ with _write_tx(conn):
424
+ cur_ops = conn.execute(
425
+ """
426
+ DELETE FROM operations
427
+ WHERE created_at < ? AND status != ?;
428
+ """,
429
+ (cutoff_iso, OpStatus.PENDING.value),
430
+ )
431
+ deleted_ops = cur_ops.rowcount
432
+
433
+ conn.execute(
434
+ "DELETE FROM events WHERE ts < ?;",
435
+ (cutoff_iso,),
436
+ )
437
+
438
+ conn.execute(
439
+ """
440
+ DELETE FROM batches
441
+ WHERE id NOT IN (SELECT DISTINCT batch_id FROM operations);
442
+ """,
443
+ )
444
+
445
+ return deleted_ops
446
+
447
+ def event_list(
448
+ self,
449
+ *,
450
+ batch_id: int | None = None,
451
+ op_id: int | None = None,
452
+ since_iso: str | None = None,
453
+ limit: int = 100,
454
+ ) -> list[dict[str, Any]]:
455
+ """Retrieve events matching optional batch_id, op_id, or since_iso filters."""
456
+ clauses: list[str] = []
457
+ params: list[Any] = []
458
+
459
+ if batch_id is not None:
460
+ clauses.append("batch_id = ?")
461
+ params.append(batch_id)
462
+
463
+ if op_id is not None:
464
+ clauses.append("op_id = ?")
465
+ params.append(op_id)
466
+
467
+ if since_iso is not None:
468
+ effective_since = self._resolve_since(since_iso)
469
+ clauses.append("ts >= ?")
470
+ params.append(effective_since)
471
+
472
+ where_sql = f"WHERE {' AND '.join(clauses)}" if clauses else ""
473
+ sql = f"SELECT * FROM events {where_sql} ORDER BY id ASC LIMIT ?;" # noqa: S608
474
+ params.append(limit)
475
+
476
+ conn = self._get_conn()
477
+ cur = conn.execute(sql, tuple(params))
478
+ results: list[dict[str, Any]] = []
479
+ for row in cur.fetchall():
480
+ path_raw = row["path"]
481
+ results.append(
482
+ {
483
+ "id": int(row["id"]),
484
+ "ts": str(row["ts"]),
485
+ "level": str(row["level"]),
486
+ "kind": str(row["kind"]),
487
+ "batch_id": int(row["batch_id"]) if row["batch_id"] is not None else None,
488
+ "op_id": int(row["op_id"]) if row["op_id"] is not None else None,
489
+ "path": pathcodec.decode(path_raw) if path_raw is not None else None,
490
+ "message": str(row["message"]),
491
+ }
492
+ )
493
+ return results