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,373 @@
1
+ """Undo service: safe rollback of file operations."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import contextlib
6
+ import hashlib
7
+ import logging
8
+ import os
9
+ import stat
10
+ from collections.abc import Sequence
11
+ from pathlib import Path
12
+
13
+ from clutterxp import locking
14
+ from clutterxp.interfaces import History, Mover
15
+ from clutterxp.models import (
16
+ ClutterError,
17
+ CollisionPolicy,
18
+ CreateDestinations,
19
+ ErrorCode,
20
+ OperationRecord,
21
+ OpStatus,
22
+ UndoOutcome,
23
+ )
24
+ from clutterxp.mover.collision import split_name_ext
25
+
26
+ logger = logging.getLogger(__name__)
27
+
28
+
29
+ def _sha256_file(path: Path) -> str:
30
+ """Compute SHA-256 digest of a file in 1 MiB chunks."""
31
+ h = hashlib.sha256()
32
+ with path.open("rb") as f:
33
+ while True:
34
+ chunk = f.read(1024 * 1024)
35
+ if not chunk:
36
+ break
37
+ h.update(chunk)
38
+ return h.hexdigest()
39
+
40
+
41
+ def _path_to_str(p: Path | None) -> str:
42
+ """Safely format a Path to string, escaping non-UTF-8 surrogates for SQLite."""
43
+ if p is None:
44
+ return ""
45
+ return os.fsencode(p).decode("utf-8", errors="backslashreplace")
46
+
47
+
48
+ class UndoService:
49
+ """Safely undoes previously executed file operations.
50
+
51
+ Adheres to safety invariants S3 (no overwrite), S4 (no delete user files),
52
+ and S15 (independent operations: one refusal does not block the batch).
53
+ """
54
+
55
+ def __init__(self, history: History, mover: Mover, fs_lock_path: Path) -> None:
56
+ """Initialize UndoService with history, mover, and lock file path."""
57
+ self.history = history
58
+ self.mover = mover
59
+ self.fs_lock_path = Path(fs_lock_path)
60
+
61
+ @staticmethod
62
+ def _matches_file_path(target: Path | None, query: Path) -> bool:
63
+ """Check if target destination path matches the query path."""
64
+ if target is None:
65
+ return False
66
+ if target == query:
67
+ return True
68
+ try:
69
+ return target.resolve() == query.resolve()
70
+ except OSError:
71
+ return False
72
+
73
+ def undo(
74
+ self,
75
+ *,
76
+ op_id: int | None = None,
77
+ batch_id: int | None = None,
78
+ file_path: Path | None = None,
79
+ dry_run: bool = False,
80
+ on_conflict: str = "skip", # "skip" | "rename"
81
+ allow_modified: bool = False,
82
+ ) -> Sequence[UndoOutcome]:
83
+ """Undo file operations matching the specified selector.
84
+
85
+ Selectors are checked in priority order:
86
+ 1. op_id: single operation
87
+ 2. batch_id: all DONE operations in the batch (reverse id order)
88
+ 3. file_path: latest DONE operation where dst_path == file_path
89
+ 4. neither: all DONE operations in the last DONE batch (reverse id order)
90
+
91
+ Args:
92
+ op_id: Specific operation id to undo.
93
+ batch_id: Batch id whose DONE operations should be undone.
94
+ file_path: Current destination path of the file to undo.
95
+ dry_run: If True, evaluate checks without modifying filesystem or history.
96
+ on_conflict: "skip" (fail if occupied) or "rename" (restore as <stem> (restored)<ext>).
97
+ allow_modified: If True, waive check 3 (size/mtime/hash verification).
98
+
99
+ Returns:
100
+ Sequence of UndoOutcome objects.
101
+ """
102
+ if on_conflict not in ("skip", "rename"):
103
+ msg = f"Invalid on_conflict policy: {on_conflict!r}. Must be 'skip' or 'rename'."
104
+ raise ValueError(msg)
105
+
106
+ ops_to_undo: list[OperationRecord] = []
107
+
108
+ if op_id is not None:
109
+ op = self.history.get_op(op_id)
110
+ if op is None:
111
+ return [
112
+ UndoOutcome(
113
+ op_id=op_id,
114
+ ok=False,
115
+ code=ErrorCode.UNDO_NOT_DONE,
116
+ message=f"Operation {op_id} not found",
117
+ )
118
+ ]
119
+ ops_to_undo = [op]
120
+ elif batch_id is not None:
121
+ ops = self.history.list_ops(batch_id=batch_id, status=OpStatus.DONE, limit=100_000)
122
+ ops_to_undo = sorted(ops, key=lambda o: o.id, reverse=True)
123
+ elif file_path is not None:
124
+ done_ops = self.history.list_ops(status=OpStatus.DONE, limit=100_000)
125
+ matching = [op for op in done_ops if self._matches_file_path(op.dst_path, file_path)]
126
+ if not matching:
127
+ return []
128
+ latest_op = max(matching, key=lambda o: o.id)
129
+ ops_to_undo = [latest_op]
130
+ else:
131
+ last_bid = self.history.last_batch_id(with_status=OpStatus.DONE)
132
+ if last_bid is None:
133
+ return []
134
+ ops = self.history.list_ops(batch_id=last_bid, status=OpStatus.DONE, limit=100_000)
135
+ ops_to_undo = sorted(ops, key=lambda o: o.id, reverse=True)
136
+
137
+ if not ops_to_undo:
138
+ return []
139
+
140
+ if not dry_run:
141
+ self.history.begin_batch("undo", note=f"Undo {len(ops_to_undo)} operations")
142
+
143
+ outcomes: list[UndoOutcome] = []
144
+ for op in ops_to_undo:
145
+ if dry_run:
146
+ outcome = self._undo_single_op(
147
+ op,
148
+ dry_run=True,
149
+ on_conflict=on_conflict,
150
+ allow_modified=allow_modified,
151
+ )
152
+ else:
153
+ try:
154
+ with locking.fs_lock(self.fs_lock_path):
155
+ outcome = self._undo_single_op(
156
+ op,
157
+ dry_run=False,
158
+ on_conflict=on_conflict,
159
+ allow_modified=allow_modified,
160
+ )
161
+ except ClutterError as e:
162
+ outcome = UndoOutcome(
163
+ op_id=op.id,
164
+ ok=False,
165
+ code=e.code,
166
+ message=str(e),
167
+ )
168
+ outcomes.append(outcome)
169
+
170
+ return outcomes
171
+
172
+ def _undo_single_op(
173
+ self,
174
+ op: OperationRecord,
175
+ *,
176
+ dry_run: bool,
177
+ on_conflict: str,
178
+ allow_modified: bool,
179
+ ) -> UndoOutcome:
180
+ """Run checks 1-5 and optionally execute the restore for a single operation."""
181
+ # Check 1: status is DONE
182
+ if op.status != OpStatus.DONE:
183
+ return UndoOutcome(
184
+ op_id=op.id,
185
+ ok=False,
186
+ code=ErrorCode.UNDO_NOT_DONE,
187
+ message=(
188
+ f"Operation {op.id} has status {op.status.value}, "
189
+ f"expected {OpStatus.DONE.value}"
190
+ ),
191
+ )
192
+
193
+ # Check 2: dst_path exists and is a regular file
194
+ if op.dst_path is None:
195
+ return UndoOutcome(
196
+ op_id=op.id,
197
+ ok=False,
198
+ code=ErrorCode.UNDO_DEST_MISSING,
199
+ message=f"Operation {op.id} destination path is missing",
200
+ )
201
+
202
+ try:
203
+ dst_st = op.dst_path.lstat()
204
+ except (FileNotFoundError, OSError):
205
+ return UndoOutcome(
206
+ op_id=op.id,
207
+ ok=False,
208
+ code=ErrorCode.UNDO_DEST_MISSING,
209
+ message=f"Destination {_path_to_str(op.dst_path)} does not exist",
210
+ )
211
+
212
+ if not stat.S_ISREG(dst_st.st_mode):
213
+ return UndoOutcome(
214
+ op_id=op.id,
215
+ ok=False,
216
+ code=ErrorCode.UNDO_DEST_MISSING,
217
+ message=f"Destination {_path_to_str(op.dst_path)} is not a regular file",
218
+ )
219
+
220
+ # Check 3: lstat(dst) size == op.size and mtime_ns == op.mtime_ns (and sha256)
221
+ size_mismatch = op.size is not None and dst_st.st_size != op.size
222
+ mtime_mismatch = op.mtime_ns is not None and dst_st.st_mtime_ns != op.mtime_ns
223
+ sha_mismatch = False
224
+ if op.sha256 is not None:
225
+ try:
226
+ cur_sha = _sha256_file(op.dst_path)
227
+ if cur_sha != op.sha256:
228
+ sha_mismatch = True
229
+ except OSError:
230
+ sha_mismatch = True
231
+
232
+ if (size_mismatch or mtime_mismatch or sha_mismatch) and not allow_modified:
233
+ details: list[str] = []
234
+ if size_mismatch:
235
+ details.append(f"size {dst_st.st_size} != recorded {op.size}")
236
+ if mtime_mismatch:
237
+ details.append(f"mtime_ns {dst_st.st_mtime_ns} != recorded {op.mtime_ns}")
238
+ if sha_mismatch:
239
+ details.append("hash mismatch")
240
+ dst_name = _path_to_str(op.dst_path)
241
+ return UndoOutcome(
242
+ op_id=op.id,
243
+ ok=False,
244
+ code=ErrorCode.UNDO_DEST_CHANGED,
245
+ message=f"Destination file {dst_name} has been modified ({', '.join(details)})",
246
+ )
247
+
248
+ # Check 4: original src_path does not exist
249
+ src_exists = os.path.lexists(op.src_path)
250
+ if src_exists:
251
+ if on_conflict == "skip":
252
+ return UndoOutcome(
253
+ op_id=op.id,
254
+ ok=False,
255
+ code=ErrorCode.UNDO_ORIGIN_OCCUPIED,
256
+ message=f"Original origin {_path_to_str(op.src_path)} is occupied",
257
+ )
258
+ # on_conflict == "rename"
259
+ stem, ext = split_name_ext(op.src_path.name)
260
+ target_name = f"{stem} (restored){ext}"
261
+ else:
262
+ target_name = op.src_path.name
263
+
264
+ target_parent = op.src_path.parent
265
+ target_path = target_parent / target_name
266
+
267
+ # Check 5: original parent directory exists / is writable
268
+ if target_parent.exists():
269
+ if not target_parent.is_dir():
270
+ return UndoOutcome(
271
+ op_id=op.id,
272
+ ok=False,
273
+ code=ErrorCode.DEST_NOT_WRITABLE,
274
+ message=(
275
+ f"Parent path {_path_to_str(target_parent)} exists but is not a directory"
276
+ ),
277
+ )
278
+ if not os.access(target_parent, os.W_OK | os.X_OK):
279
+ return UndoOutcome(
280
+ op_id=op.id,
281
+ ok=False,
282
+ code=ErrorCode.DEST_NOT_WRITABLE,
283
+ message=f"Parent directory {_path_to_str(target_parent)} is not writable",
284
+ )
285
+ else:
286
+ curr = target_parent
287
+ while not curr.exists() and curr.parent != curr:
288
+ curr = curr.parent
289
+ if not curr.exists() or not curr.is_dir() or not os.access(curr, os.W_OK | os.X_OK):
290
+ return UndoOutcome(
291
+ op_id=op.id,
292
+ ok=False,
293
+ code=ErrorCode.DEST_NOT_WRITABLE,
294
+ message=(
295
+ f"Cannot recreate parent directory {_path_to_str(target_parent)}: "
296
+ f"ancestor {_path_to_str(curr)} is not writable"
297
+ ),
298
+ )
299
+
300
+ # Dry-run evaluation: return outcome without any filesystem or history mutations
301
+ if dry_run:
302
+ if os.path.lexists(target_path):
303
+ return UndoOutcome(
304
+ op_id=op.id,
305
+ ok=False,
306
+ code=ErrorCode.COLLISION,
307
+ message=f"Restored destination {_path_to_str(target_path)} already exists",
308
+ )
309
+ return UndoOutcome(
310
+ op_id=op.id,
311
+ ok=True,
312
+ restored_to=target_path,
313
+ code=ErrorCode.NONE,
314
+ message=(
315
+ f"Would restore {_path_to_str(op.dst_path)} to {_path_to_str(target_path)}"
316
+ ),
317
+ )
318
+
319
+ # Execute restore
320
+ parent_was_missing = not target_parent.exists()
321
+
322
+ move_res = self.mover.move_file(
323
+ op.dst_path,
324
+ target_parent,
325
+ new_name=target_name,
326
+ collision=CollisionPolicy.SKIP,
327
+ create=CreateDestinations.ALL,
328
+ )
329
+
330
+ if not move_res.ok:
331
+ return UndoOutcome(
332
+ op_id=op.id,
333
+ ok=False,
334
+ code=move_res.code,
335
+ message=move_res.message,
336
+ )
337
+
338
+ effective_restored_to = move_res.dst or target_path
339
+ dst_display = _path_to_str(op.dst_path)
340
+ restored_display = _path_to_str(effective_restored_to)
341
+
342
+ if parent_was_missing:
343
+ self.history.record_event(
344
+ "info",
345
+ f"Recreated missing destination directory {_path_to_str(target_parent)}",
346
+ op_id=op.id,
347
+ batch_id=op.batch_id,
348
+ path=target_parent,
349
+ )
350
+
351
+ self.history.mark_undone(op.id)
352
+ self.history.record_event(
353
+ "undo",
354
+ f"Restored {dst_display} to {restored_display}",
355
+ op_id=op.id,
356
+ batch_id=op.batch_id,
357
+ )
358
+
359
+ # Clean up op.created_dirs ONLY if empty, deepest first
360
+ if op.created_dirs:
361
+ sorted_dirs = sorted(op.created_dirs, key=lambda p: len(p.parts), reverse=True)
362
+ for d in sorted_dirs:
363
+ with contextlib.suppress(OSError):
364
+ os.rmdir(d) # noqa: PTH106
365
+
366
+ return UndoOutcome(
367
+ op_id=op.id,
368
+ ok=True,
369
+ restored_to=effective_restored_to,
370
+ )
371
+
372
+
373
+ __all__ = ["UndoService"]
@@ -0,0 +1,164 @@
1
+ """ClutterXP module interfaces (FROZEN).
2
+
3
+ These Protocols let agents build modules in parallel: each agent implements its
4
+ Protocol and tests against fakes of the others. Changing a signature requires a
5
+ CONTRACT_CHANGE request (see AGENTS.md).
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from pathlib import Path
11
+ from typing import Iterable, Protocol, Sequence, runtime_checkable
12
+
13
+ from .models import (
14
+ BatchResult,
15
+ CollisionPolicy,
16
+ CreateDestinations,
17
+ Decision,
18
+ DuplicateGroup,
19
+ ErrorCode,
20
+ FileInfo,
21
+ MoveResult,
22
+ OperationRecord,
23
+ OpStatus,
24
+ Plan,
25
+ ProgressCb,
26
+ RuleTrace,
27
+ UndoOutcome,
28
+ )
29
+
30
+
31
+ @runtime_checkable
32
+ class RuleEngine(Protocol):
33
+ """Pure: no filesystem writes, no file-content reads. stat() data comes in via FileInfo."""
34
+
35
+ def decide(self, file: FileInfo, *, folder: Path | None = None) -> Decision:
36
+ """`folder` is the watched/scanned root; used to apply per-folder rule subsets."""
37
+
38
+ def trace(self, file: FileInfo) -> Sequence[RuleTrace]:
39
+ """Explain every rule's match/non-match for one file (`rules test`)."""
40
+
41
+
42
+ @runtime_checkable
43
+ class Mover(Protocol):
44
+ """Filesystem primitive. Never deletes user data except the source after a verified publish."""
45
+
46
+ def move_file(
47
+ self,
48
+ src: Path,
49
+ dest_dir: Path,
50
+ *,
51
+ new_name: str | None = None,
52
+ collision: CollisionPolicy = CollisionPolicy.SKIP,
53
+ create: CreateDestinations = CreateDestinations.LEAF,
54
+ static_root: Path | None = None,
55
+ expect_size: int | None = None,
56
+ expect_mtime_ns: int | None = None,
57
+ progress: ProgressCb | None = None,
58
+ ) -> MoveResult: ...
59
+
60
+
61
+ @runtime_checkable
62
+ class History(Protocol):
63
+ def begin_batch(
64
+ self, command: str, folder: Path | None = None, note: str | None = None
65
+ ) -> int: ...
66
+
67
+ def begin_op(self, batch_id: int, src: Path, rule_name: str | None, file: FileInfo) -> int:
68
+ """Insert status=pending BEFORE any filesystem change. Must be durable on return."""
69
+
70
+ def finish_op(self, op_id: int, result: MoveResult) -> None:
71
+ """Mark done/failed with final dst, strategy and created_dirs."""
72
+
73
+ def record_event(
74
+ self,
75
+ kind: str,
76
+ message: str,
77
+ *,
78
+ level: str = "info",
79
+ batch_id: int | None = None,
80
+ op_id: int | None = None,
81
+ path: Path | None = None,
82
+ ) -> None: ...
83
+
84
+ def get_op(self, op_id: int) -> OperationRecord | None: ...
85
+
86
+ def list_ops(
87
+ self,
88
+ *,
89
+ batch_id: int | None = None,
90
+ status: OpStatus | None = None,
91
+ limit: int = 50,
92
+ since_iso: str | None = None,
93
+ rule_name: str | None = None,
94
+ path_contains: str | None = None,
95
+ ) -> Sequence[OperationRecord]: ...
96
+
97
+ def last_batch_id(self, *, with_status: OpStatus = OpStatus.DONE) -> int | None: ...
98
+
99
+ def mark_undone(self, op_id: int) -> None: ...
100
+
101
+ def pending_ops(self) -> Sequence[OperationRecord]: ...
102
+
103
+
104
+ @runtime_checkable
105
+ class Organizer(Protocol):
106
+ """The single facade used by the CLI, the watcher and the GUI."""
107
+
108
+ def plan(
109
+ self,
110
+ paths: Iterable[Path] | None = None,
111
+ *,
112
+ recursive: bool | None = None,
113
+ only_rules: Sequence[str] | None = None,
114
+ ) -> Plan: ...
115
+
116
+ def apply(
117
+ self,
118
+ plan: Plan,
119
+ *,
120
+ command: str = "organize",
121
+ progress: ProgressCb | None = None,
122
+ ) -> BatchResult: ...
123
+
124
+ def process_file(
125
+ self, path: Path, *, folder: Path | None = None, command: str = "watch"
126
+ ) -> BatchResult:
127
+ """Single-file path used by the watcher: decide -> plan -> apply, one batch of one op."""
128
+
129
+ def undo(
130
+ self,
131
+ *,
132
+ op_id: int | None = None,
133
+ batch_id: int | None = None,
134
+ dry_run: bool = False,
135
+ on_conflict: str = "skip",
136
+ allow_modified: bool = False,
137
+ ) -> Sequence[UndoOutcome]: ...
138
+
139
+ def reload_config(self) -> None: ...
140
+
141
+
142
+ @runtime_checkable
143
+ class DuplicateDetector(Protocol):
144
+ def scan(
145
+ self,
146
+ folders: Sequence[Path],
147
+ *,
148
+ recursive: bool = True,
149
+ min_size: int = 1,
150
+ exclude: Sequence[str] = (),
151
+ jobs: int = 1,
152
+ potential: bool = True,
153
+ progress: ProgressCb | None = None,
154
+ ) -> Sequence[DuplicateGroup]: ...
155
+
156
+
157
+ __all__ = [
158
+ "RuleEngine",
159
+ "Mover",
160
+ "History",
161
+ "Organizer",
162
+ "DuplicateDetector",
163
+ "ErrorCode",
164
+ ]
clutterxp/locking.py ADDED
@@ -0,0 +1,113 @@
1
+ """Locking utilities: filesystem exclusive lock and watch lock."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import contextlib
6
+ import errno
7
+ import fcntl
8
+ import os
9
+ import time
10
+ from collections.abc import Generator
11
+ from contextlib import contextmanager
12
+ from pathlib import Path
13
+
14
+ from clutterxp.models import ClutterError, ErrorCode
15
+
16
+
17
+ def _open_lock_file(lock_path: Path) -> int:
18
+ """Open or create a lock file with 0600 permissions."""
19
+ lock_path.parent.mkdir(parents=True, exist_ok=True)
20
+ fd = os.open(lock_path, os.O_RDWR | os.O_CREAT, 0o600)
21
+ with contextlib.suppress(OSError):
22
+ lock_path.chmod(0o600)
23
+ return fd
24
+
25
+
26
+ @contextmanager
27
+ def fs_lock(lock_path: Path, timeout: float = 10.0) -> Generator[None, None, None]:
28
+ """Exclusive flock, timeout raises ClutterError(code=LOCK_TIMEOUT).
29
+
30
+ Lock file created 0600. Released by kernel on crash.
31
+ """
32
+ fd = _open_lock_file(lock_path)
33
+ start = time.monotonic()
34
+ deadline = start + timeout
35
+ acquired = False
36
+
37
+ try:
38
+ while True:
39
+ try:
40
+ fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
41
+ acquired = True
42
+ break
43
+ except (BlockingIOError, OSError) as e:
44
+ err = getattr(e, "errno", None)
45
+ if err not in (errno.EACCES, errno.EAGAIN, errno.EWOULDBLOCK):
46
+ raise
47
+ if time.monotonic() >= deadline:
48
+ break
49
+ rem = deadline - time.monotonic()
50
+ if rem <= 0:
51
+ break
52
+ time.sleep(min(0.05, max(0.001, rem)))
53
+
54
+ if not acquired:
55
+ raise ClutterError(
56
+ f"Could not acquire filesystem lock at {lock_path} within {timeout}s",
57
+ code=ErrorCode.LOCK_TIMEOUT,
58
+ )
59
+
60
+ yield
61
+ finally:
62
+ if acquired:
63
+ with contextlib.suppress(OSError):
64
+ fcntl.flock(fd, fcntl.LOCK_UN)
65
+ with contextlib.suppress(OSError):
66
+ os.close(fd)
67
+
68
+
69
+ @contextmanager
70
+ def watch_lock(lock_path: Path) -> Generator[None, None, None]:
71
+ """Non-blocking flock. Raises ClutterError with PID of holder if locked.
72
+
73
+ Writes own PID to lock file. Lock file 0600.
74
+ """
75
+ fd = _open_lock_file(lock_path)
76
+ acquired = False
77
+
78
+ try:
79
+ try:
80
+ fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
81
+ acquired = True
82
+ except (BlockingIOError, OSError) as e:
83
+ err = getattr(e, "errno", None)
84
+ if err in (errno.EACCES, errno.EAGAIN, errno.EWOULDBLOCK):
85
+ pid_holder = "unknown"
86
+ with contextlib.suppress(OSError), lock_path.open(encoding="utf-8") as f:
87
+ content = f.read().strip()
88
+ if content:
89
+ pid_holder = content
90
+ raise ClutterError(
91
+ f"Watch lock at {lock_path} is already held by PID {pid_holder}",
92
+ code=ErrorCode.LOCK_TIMEOUT,
93
+ ) from None
94
+ raise
95
+
96
+ with contextlib.suppress(OSError):
97
+ os.ftruncate(fd, 0)
98
+ os.lseek(fd, 0, os.SEEK_SET)
99
+ os.write(fd, f"{os.getpid()}\n".encode())
100
+ os.fsync(fd)
101
+
102
+ yield
103
+ finally:
104
+ if acquired:
105
+ with contextlib.suppress(OSError):
106
+ os.ftruncate(fd, 0)
107
+ with contextlib.suppress(OSError):
108
+ fcntl.flock(fd, fcntl.LOCK_UN)
109
+ with contextlib.suppress(OSError):
110
+ os.close(fd)
111
+
112
+
113
+ __all__ = ["fs_lock", "watch_lock"]