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,741 @@
1
+ """Safe file mover implementation conforming to Mover Protocol."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import contextlib
6
+ import errno
7
+ import hashlib
8
+ import logging
9
+ import os
10
+ import shutil
11
+ import stat
12
+ import time
13
+ import uuid
14
+ from collections.abc import Generator
15
+ from pathlib import Path
16
+ from typing import Any, Literal
17
+
18
+ from clutterxp.models import (
19
+ CollisionPolicy,
20
+ CreateDestinations,
21
+ ErrorCode,
22
+ MoveResult,
23
+ MoveStrategy,
24
+ ProgressCb,
25
+ )
26
+ from clutterxp.mover import fsops
27
+ from clutterxp.mover.collision import candidate_names
28
+
29
+ logger = logging.getLogger(__name__)
30
+
31
+
32
+ def _hash_file(path: Path) -> str:
33
+ """Compute SHA-256 digest of a file in 1 MiB chunks."""
34
+ h = hashlib.sha256()
35
+ with path.open("rb") as f:
36
+ while True:
37
+ chunk = f.read(1024 * 1024)
38
+ if not chunk:
39
+ break
40
+ h.update(chunk)
41
+ return h.hexdigest()
42
+
43
+
44
+ class SafeMover:
45
+ """Safe mover with atomic publish, collision policies, and cross-filesystem fallback."""
46
+
47
+ def __init__(
48
+ self,
49
+ *,
50
+ verify_copy: Literal["size", "hash"] = "size",
51
+ fs: Any = None,
52
+ ) -> None:
53
+ self._verify_copy = verify_copy
54
+ self._fs = fs if fs is not None else fsops
55
+
56
+ def move_file(
57
+ self,
58
+ src: Path,
59
+ dest_dir: Path,
60
+ *,
61
+ new_name: str | None = None,
62
+ collision: CollisionPolicy = CollisionPolicy.SKIP,
63
+ create: CreateDestinations = CreateDestinations.LEAF,
64
+ static_root: Path | None = None,
65
+ expect_size: int | None = None,
66
+ expect_mtime_ns: int | None = None,
67
+ progress: ProgressCb | None = None,
68
+ ) -> MoveResult:
69
+ """Move a single regular file to dest_dir safely."""
70
+ created_dirs: list[Path] = []
71
+
72
+ try:
73
+ # 1. Precondition: src exists and is a regular file
74
+ try:
75
+ st = src.lstat()
76
+ except FileNotFoundError:
77
+ return MoveResult(
78
+ ok=False,
79
+ src=src,
80
+ dst=None,
81
+ strategy=None,
82
+ code=ErrorCode.SRC_VANISHED,
83
+ message=f"Source file {src} does not exist",
84
+ )
85
+ except OSError as e:
86
+ code = (
87
+ ErrorCode.PERMISSION
88
+ if e.errno in (errno.EACCES, errno.EPERM)
89
+ else ErrorCode.UNKNOWN
90
+ )
91
+ return MoveResult(
92
+ ok=False,
93
+ src=src,
94
+ dst=None,
95
+ strategy=None,
96
+ code=code,
97
+ message=str(e),
98
+ )
99
+
100
+ if stat.S_ISLNK(st.st_mode) or not stat.S_ISREG(st.st_mode):
101
+ return MoveResult(
102
+ ok=False,
103
+ src=src,
104
+ dst=None,
105
+ strategy=None,
106
+ code=ErrorCode.SRC_NOT_REGULAR,
107
+ message=f"Source {src} is not a regular file",
108
+ )
109
+
110
+ # 2. Precondition: expect_size and expect_mtime_ns (TOCTOU re-check)
111
+ if expect_size is not None and st.st_size != expect_size:
112
+ return MoveResult(
113
+ ok=False,
114
+ src=src,
115
+ dst=None,
116
+ strategy=None,
117
+ code=ErrorCode.SRC_CHANGED,
118
+ message=f"Source size changed: expected {expect_size}, got {st.st_size}",
119
+ )
120
+ if expect_mtime_ns is not None and st.st_mtime_ns != expect_mtime_ns:
121
+ msg = f"Source mtime changed: expected {expect_mtime_ns}, got {st.st_mtime_ns}"
122
+ return MoveResult(
123
+ ok=False,
124
+ src=src,
125
+ dst=None,
126
+ strategy=None,
127
+ code=ErrorCode.SRC_CHANGED,
128
+ message=msg,
129
+ )
130
+
131
+ # Precondition: Final name validation
132
+ dst_name = new_name if new_name is not None else src.name
133
+ if "/" in dst_name or "\x00" in dst_name or dst_name in (".", ".."):
134
+ return MoveResult(
135
+ ok=False,
136
+ src=src,
137
+ dst=None,
138
+ strategy=None,
139
+ code=ErrorCode.DEST_INVALID,
140
+ message=f"Invalid destination file name: {dst_name!r}",
141
+ )
142
+
143
+ # Precondition: destination directory is not source's own directory (no-op)
144
+ try:
145
+ if dest_dir.resolve() == src.parent.resolve() and dst_name == src.name:
146
+ return MoveResult(
147
+ ok=False,
148
+ src=src,
149
+ dst=None,
150
+ strategy=None,
151
+ code=ErrorCode.DEST_INVALID,
152
+ message="Destination directory is source's own directory (no-op)",
153
+ )
154
+ except OSError:
155
+ pass
156
+
157
+ # 3. Precondition: Destination directory creation per `create` mode
158
+ dest_res = self._prepare_dest_dir(dest_dir, create, static_root, created_dirs)
159
+ if dest_res is not None:
160
+ return dest_res
161
+
162
+ # Precondition: dest_dir writable
163
+ if not os.access(dest_dir, os.W_OK | os.X_OK):
164
+ return MoveResult(
165
+ ok=False,
166
+ src=src,
167
+ dst=None,
168
+ strategy=None,
169
+ code=ErrorCode.DEST_NOT_WRITABLE,
170
+ message=f"Destination directory {dest_dir} is not writable",
171
+ created_dirs=tuple(created_dirs),
172
+ )
173
+
174
+ # Precondition: Enough space (best-effort)
175
+ is_same_fs = self._fs.same_device(src, dest_dir)
176
+ if not is_same_fs:
177
+ try:
178
+ usage = shutil.disk_usage(dest_dir)
179
+ if usage.free < st.st_size:
180
+ return MoveResult(
181
+ ok=False,
182
+ src=src,
183
+ dst=None,
184
+ strategy=None,
185
+ code=ErrorCode.NO_SPACE,
186
+ message=f"Not enough space in {dest_dir}: {usage.free} < {st.st_size}",
187
+ created_dirs=tuple(created_dirs),
188
+ )
189
+ except OSError:
190
+ pass
191
+
192
+ # Precondition 4 & Collision handling:
193
+ if is_same_fs:
194
+ try:
195
+ return self._move_strategy_a(
196
+ src=src,
197
+ dest_dir=dest_dir,
198
+ dst_name=dst_name,
199
+ collision=collision,
200
+ created_dirs=created_dirs,
201
+ )
202
+ except OSError as err:
203
+ if err.errno == errno.EXDEV:
204
+ # Cross-filesystem detected/simulated, switch to Strategy B
205
+ return self._move_strategy_b(
206
+ src=src,
207
+ dest_dir=dest_dir,
208
+ dst_name=dst_name,
209
+ collision=collision,
210
+ created_dirs=created_dirs,
211
+ progress=progress,
212
+ )
213
+ raise
214
+ else:
215
+ return self._move_strategy_b(
216
+ src=src,
217
+ dest_dir=dest_dir,
218
+ dst_name=dst_name,
219
+ collision=collision,
220
+ created_dirs=created_dirs,
221
+ progress=progress,
222
+ )
223
+
224
+ except OSError as e:
225
+ code = ErrorCode.UNKNOWN
226
+ if e.errno == errno.ENOSPC:
227
+ code = ErrorCode.NO_SPACE
228
+ elif e.errno in (errno.EACCES, errno.EPERM):
229
+ code = ErrorCode.PERMISSION
230
+ elif e.errno == errno.ENOENT:
231
+ code = ErrorCode.SRC_VANISHED
232
+ return MoveResult(
233
+ ok=False,
234
+ src=src,
235
+ dst=None,
236
+ strategy=None,
237
+ code=code,
238
+ message=str(e),
239
+ created_dirs=tuple(created_dirs),
240
+ )
241
+
242
+ def _prepare_dest_dir(
243
+ self,
244
+ dest_dir: Path,
245
+ create: CreateDestinations,
246
+ static_root: Path | None,
247
+ created_dirs: list[Path],
248
+ ) -> MoveResult | None:
249
+ """Create destination directories per policy, recording created paths deepest-last."""
250
+ # Reject any destination directory containing a symlink component
251
+ curr_check = dest_dir
252
+ while curr_check != curr_check.parent:
253
+ if curr_check.is_symlink():
254
+ return MoveResult(
255
+ ok=False,
256
+ src=dest_dir,
257
+ dst=None,
258
+ strategy=None,
259
+ code=ErrorCode.DEST_INVALID,
260
+ message=f"Destination component {curr_check} is a symlink",
261
+ created_dirs=tuple(created_dirs),
262
+ )
263
+ curr_check = curr_check.parent
264
+
265
+ if create == CreateDestinations.NEVER:
266
+ if not dest_dir.exists() or not dest_dir.is_dir():
267
+ return MoveResult(
268
+ ok=False,
269
+ src=dest_dir,
270
+ dst=None,
271
+ strategy=None,
272
+ code=ErrorCode.DEST_MISSING,
273
+ message=f"Destination directory {dest_dir} does not exist",
274
+ )
275
+ return None
276
+
277
+ if create == CreateDestinations.LEAF:
278
+ if dest_dir.is_dir():
279
+ return None
280
+
281
+ if static_root is not None:
282
+ # static_root must exist or its parent must exist
283
+ if not static_root.exists():
284
+ if static_root.parent.is_dir():
285
+ static_root.mkdir()
286
+ created_dirs.append(static_root)
287
+ else:
288
+ return MoveResult(
289
+ ok=False,
290
+ src=dest_dir,
291
+ dst=None,
292
+ strategy=None,
293
+ code=ErrorCode.DEST_MISSING,
294
+ message=f"Static root parent {static_root.parent} does not exist",
295
+ )
296
+
297
+ # Subdirectories below static_root up to dest_dir are created
298
+ try:
299
+ rel = dest_dir.relative_to(static_root)
300
+ curr = static_root
301
+ for part in rel.parts:
302
+ curr = curr / part
303
+ if curr.is_symlink():
304
+ return MoveResult(
305
+ ok=False,
306
+ src=dest_dir,
307
+ dst=None,
308
+ strategy=None,
309
+ code=ErrorCode.DEST_INVALID,
310
+ message=f"Path component {curr} is a symlink",
311
+ created_dirs=tuple(created_dirs),
312
+ )
313
+ if not curr.exists():
314
+ curr.mkdir()
315
+ created_dirs.append(curr)
316
+ except ValueError:
317
+ # dest_dir is not relative to static_root, check leaf parent
318
+ if not dest_dir.parent.is_dir():
319
+ return MoveResult(
320
+ ok=False,
321
+ src=dest_dir,
322
+ dst=None,
323
+ strategy=None,
324
+ code=ErrorCode.DEST_MISSING,
325
+ message=f"Destination parent {dest_dir.parent} does not exist",
326
+ )
327
+ dest_dir.mkdir()
328
+ created_dirs.append(dest_dir)
329
+ else:
330
+ if not dest_dir.parent.is_dir():
331
+ return MoveResult(
332
+ ok=False,
333
+ src=dest_dir,
334
+ dst=None,
335
+ strategy=None,
336
+ code=ErrorCode.DEST_MISSING,
337
+ message=f"Destination parent {dest_dir.parent} does not exist",
338
+ )
339
+ dest_dir.mkdir()
340
+ created_dirs.append(dest_dir)
341
+ return None
342
+
343
+ if create == CreateDestinations.ALL:
344
+ if dest_dir.is_dir():
345
+ return None
346
+ if dest_dir.exists() and not dest_dir.is_dir():
347
+ return MoveResult(
348
+ ok=False,
349
+ src=dest_dir,
350
+ dst=None,
351
+ strategy=None,
352
+ code=ErrorCode.DEST_MISSING,
353
+ message=f"Destination path {dest_dir} exists and is not a directory",
354
+ )
355
+ to_create: list[Path] = []
356
+ curr = dest_dir
357
+ while not curr.exists() and curr != curr.parent:
358
+ if curr.is_symlink():
359
+ return MoveResult(
360
+ ok=False,
361
+ src=dest_dir,
362
+ dst=None,
363
+ strategy=None,
364
+ code=ErrorCode.DEST_INVALID,
365
+ message=f"Path component {curr} is a symlink",
366
+ created_dirs=tuple(created_dirs),
367
+ )
368
+ to_create.append(curr)
369
+ curr = curr.parent
370
+ to_create.reverse()
371
+ for d in to_create:
372
+ d.mkdir()
373
+ created_dirs.append(d)
374
+ return None
375
+
376
+ return None
377
+
378
+ def _publish_same_fs(
379
+ self,
380
+ src: Path,
381
+ dst: Path,
382
+ ) -> tuple[bool, MoveStrategy | None, bool]:
383
+ """Publish src to dst on the same filesystem.
384
+
385
+ Returns (success, strategy, unlink_failed).
386
+ """
387
+ # 1. rename_noreplace
388
+ try:
389
+ if self._fs.rename_noreplace(src, dst):
390
+ return True, MoveStrategy.RENAME_NOREPLACE, False
391
+ except OSError as e:
392
+ if e.errno == errno.EXDEV:
393
+ raise
394
+ # Fall through to next strategy on non-fatal errors
395
+
396
+ # If rename_noreplace returned False, check if dst exists (collision)
397
+ if os.path.lexists(dst):
398
+ return False, None, False
399
+
400
+ # 2. link_unlink
401
+ try:
402
+ if self._fs.link_unlink(src, dst):
403
+ return True, MoveStrategy.LINK_UNLINK, False
404
+ else:
405
+ # Check if link succeeded but unlink failed!
406
+ if os.path.lexists(dst) and os.path.lexists(src):
407
+ with contextlib.suppress(OSError):
408
+ if dst.stat().st_ino == src.stat().st_ino:
409
+ return False, MoveStrategy.LINK_UNLINK, True
410
+ except OSError as e:
411
+ if e.errno == errno.EXDEV:
412
+ raise
413
+
414
+ if os.path.lexists(dst):
415
+ return False, None, False
416
+
417
+ # 3. checked_rename
418
+ try:
419
+ if self._fs.checked_rename(src, dst):
420
+ return True, MoveStrategy.CHECKED_RENAME, False
421
+ except OSError as e:
422
+ if e.errno == errno.EXDEV:
423
+ raise
424
+
425
+ return False, None, False
426
+
427
+ def _candidates_for(
428
+ self,
429
+ dst_name: str,
430
+ collision: CollisionPolicy,
431
+ ) -> Generator[str, None, None]:
432
+ """Generate candidate destination names based on collision policy."""
433
+ yield dst_name
434
+ if collision == CollisionPolicy.RENAME:
435
+ yield from candidate_names(dst_name)
436
+
437
+ def _move_strategy_a(
438
+ self,
439
+ src: Path,
440
+ dest_dir: Path,
441
+ dst_name: str,
442
+ collision: CollisionPolicy,
443
+ created_dirs: list[Path],
444
+ ) -> MoveResult:
445
+ """Strategy A: same filesystem move using atomic no-clobber primitives."""
446
+ # Check initial collision for SKIP policy
447
+ initial_dst = dest_dir / dst_name
448
+ if collision == CollisionPolicy.SKIP and os.path.lexists(initial_dst):
449
+ return MoveResult(
450
+ ok=False,
451
+ src=src,
452
+ dst=None,
453
+ strategy=None,
454
+ code=ErrorCode.COLLISION,
455
+ message=f"Destination {initial_dst} already exists",
456
+ created_dirs=tuple(created_dirs),
457
+ )
458
+
459
+ for cand_name in self._candidates_for(dst_name, collision):
460
+ cand_path = dest_dir / cand_name
461
+
462
+ # Skip existing candidates in RENAME policy
463
+ if os.path.lexists(cand_path):
464
+ if collision == CollisionPolicy.SKIP:
465
+ return MoveResult(
466
+ ok=False,
467
+ src=src,
468
+ dst=None,
469
+ strategy=None,
470
+ code=ErrorCode.COLLISION,
471
+ message=f"Destination {cand_path} already exists",
472
+ created_dirs=tuple(created_dirs),
473
+ )
474
+ continue
475
+
476
+ success, strategy, unlink_failed = self._publish_same_fs(src, cand_path)
477
+
478
+ if unlink_failed:
479
+ # Link succeeded but unlink(src) failed: keep dst, return PERMISSION
480
+ return MoveResult(
481
+ ok=False,
482
+ src=src,
483
+ dst=cand_path,
484
+ strategy=MoveStrategy.LINK_UNLINK,
485
+ code=ErrorCode.PERMISSION,
486
+ message="copied but could not remove source",
487
+ created_dirs=tuple(created_dirs),
488
+ renamed_due_to_collision=(cand_path.name != dst_name),
489
+ )
490
+
491
+ if success:
492
+ renamed = cand_path.name != dst_name
493
+ return MoveResult(
494
+ ok=True,
495
+ src=src,
496
+ dst=cand_path,
497
+ strategy=strategy,
498
+ code=ErrorCode.NONE,
499
+ message="",
500
+ created_dirs=tuple(created_dirs),
501
+ renamed_due_to_collision=renamed,
502
+ bytes_copied=0,
503
+ )
504
+
505
+ # Failure: another process occupied cand_path (race collision)
506
+ if collision == CollisionPolicy.SKIP:
507
+ return MoveResult(
508
+ ok=False,
509
+ src=src,
510
+ dst=None,
511
+ strategy=None,
512
+ code=ErrorCode.COLLISION,
513
+ message=f"Destination {cand_path} already exists",
514
+ created_dirs=tuple(created_dirs),
515
+ )
516
+
517
+ return MoveResult(
518
+ ok=False,
519
+ src=src,
520
+ dst=None,
521
+ strategy=None,
522
+ code=ErrorCode.COLLISION,
523
+ message="Too many collisions (capped at 9999)",
524
+ created_dirs=tuple(created_dirs),
525
+ )
526
+
527
+ def _move_strategy_b(
528
+ self,
529
+ src: Path,
530
+ dest_dir: Path,
531
+ dst_name: str,
532
+ collision: CollisionPolicy,
533
+ created_dirs: list[Path],
534
+ progress: ProgressCb | None,
535
+ ) -> MoveResult:
536
+ """Strategy B: cross-filesystem copy-verify-publish-unlink move."""
537
+ # 1. Record size0 and mtime_ns0
538
+ st0 = src.lstat()
539
+ size0 = st0.st_size
540
+ mtime_ns0 = st0.st_mtime_ns
541
+ atime_ns0 = st0.st_atime_ns
542
+ mode0 = st0.st_mode
543
+
544
+ # Check initial collision for SKIP policy
545
+ initial_dst = dest_dir / dst_name
546
+ if collision == CollisionPolicy.SKIP and os.path.lexists(initial_dst):
547
+ return MoveResult(
548
+ ok=False,
549
+ src=src,
550
+ dst=None,
551
+ strategy=None,
552
+ code=ErrorCode.COLLISION,
553
+ message=f"Destination {initial_dst} already exists",
554
+ created_dirs=tuple(created_dirs),
555
+ )
556
+
557
+ # 2. Create temp file in dest_dir
558
+ temp_name = f".{dst_name}.{os.getpid()}.{uuid.uuid4().hex[:8]}.clutterxp-partial"
559
+ temp_path = dest_dir / temp_name
560
+ published = False
561
+
562
+ try:
563
+ fd = os.open(temp_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
564
+ try:
565
+ # Copy in 1 MiB chunks
566
+ chunk_size = 1024 * 1024
567
+ copied = 0
568
+ last_progress_time = 0.0
569
+
570
+ with src.open("rb") as fsrc, open(fd, "wb", closefd=False) as fdst:
571
+ while True:
572
+ chunk = fsrc.read(chunk_size)
573
+ if not chunk:
574
+ break
575
+ fdst.write(chunk)
576
+ copied += len(chunk)
577
+ if progress is not None:
578
+ now = time.monotonic()
579
+ if now - last_progress_time >= 0.1 or copied >= size0:
580
+ progress(copied, size0)
581
+ last_progress_time = now
582
+
583
+ if size0 == 0 and progress is not None:
584
+ progress(0, 0)
585
+ fdst.flush()
586
+
587
+ # 3. fsync temp file
588
+ self._fs.fsync_file(temp_path)
589
+ finally:
590
+ os.close(fd)
591
+
592
+ # 4. Verify
593
+ # Re-stat src
594
+ st_check1 = src.lstat()
595
+ if st_check1.st_size != size0 or st_check1.st_mtime_ns != mtime_ns0:
596
+ return MoveResult(
597
+ ok=False,
598
+ src=src,
599
+ dst=None,
600
+ strategy=None,
601
+ code=ErrorCode.SRC_CHANGED,
602
+ message="Source changed during copy",
603
+ created_dirs=tuple(created_dirs),
604
+ )
605
+
606
+ # Verify temp size
607
+ st_temp = temp_path.stat()
608
+ if st_temp.st_size != size0:
609
+ return MoveResult(
610
+ ok=False,
611
+ src=src,
612
+ dst=None,
613
+ strategy=None,
614
+ code=ErrorCode.VERIFY_FAILED,
615
+ message=f"Temp file size mismatch: {st_temp.st_size} != {size0}",
616
+ created_dirs=tuple(created_dirs),
617
+ )
618
+
619
+ # Verify hash if configured
620
+ if self._verify_copy == "hash":
621
+ src_hash = _hash_file(src)
622
+ temp_hash = _hash_file(temp_path)
623
+ if src_hash != temp_hash:
624
+ return MoveResult(
625
+ ok=False,
626
+ src=src,
627
+ dst=None,
628
+ strategy=None,
629
+ code=ErrorCode.VERIFY_FAILED,
630
+ message="SHA-256 hash mismatch between source and destination copy",
631
+ created_dirs=tuple(created_dirs),
632
+ )
633
+
634
+ # 5. Re-stat src again to catch any change during hashing
635
+ st_check2 = src.lstat()
636
+ if st_check2.st_size != size0 or st_check2.st_mtime_ns != mtime_ns0:
637
+ return MoveResult(
638
+ ok=False,
639
+ src=src,
640
+ dst=None,
641
+ strategy=None,
642
+ code=ErrorCode.SRC_CHANGED,
643
+ message="Source changed during copy",
644
+ created_dirs=tuple(created_dirs),
645
+ )
646
+
647
+ # 6. Apply metadata to temp file
648
+ temp_path.chmod(mode0)
649
+ os.utime(temp_path, ns=(atime_ns0, mtime_ns0))
650
+ with contextlib.suppress(OSError, PermissionError):
651
+ shutil.copystat(src, temp_path, follow_symlinks=False)
652
+
653
+ # 7. Publish with no-clobber primitive
654
+ target_path: Path | None = None
655
+ for cand_name in self._candidates_for(dst_name, collision):
656
+ cand_path = dest_dir / cand_name
657
+ if os.path.lexists(cand_path):
658
+ if collision == CollisionPolicy.SKIP:
659
+ return MoveResult(
660
+ ok=False,
661
+ src=src,
662
+ dst=None,
663
+ strategy=None,
664
+ code=ErrorCode.COLLISION,
665
+ message=f"Destination {cand_path} already exists",
666
+ created_dirs=tuple(created_dirs),
667
+ )
668
+ continue
669
+
670
+ success, _, _ = self._publish_same_fs(temp_path, cand_path)
671
+ if success:
672
+ target_path = cand_path
673
+ published = True
674
+ break
675
+
676
+ if collision == CollisionPolicy.SKIP:
677
+ return MoveResult(
678
+ ok=False,
679
+ src=src,
680
+ dst=None,
681
+ strategy=None,
682
+ code=ErrorCode.COLLISION,
683
+ message=f"Destination {cand_path} already exists",
684
+ created_dirs=tuple(created_dirs),
685
+ )
686
+
687
+ if target_path is None or not published:
688
+ return MoveResult(
689
+ ok=False,
690
+ src=src,
691
+ dst=None,
692
+ strategy=None,
693
+ code=ErrorCode.COLLISION,
694
+ message="Could not publish destination file (too many collisions or race)",
695
+ created_dirs=tuple(created_dirs),
696
+ )
697
+
698
+ # 8. fsync dest_dir
699
+ self._fs.fsync_dir(dest_dir)
700
+
701
+ # 9. Unlink src
702
+ try:
703
+ src.unlink()
704
+ except OSError as err:
705
+ # Keep both files! Do NOT delete target_path!
706
+ logger.warning("Unlink source '%s' failed after verified copy: %s", src, err)
707
+ return MoveResult(
708
+ ok=False,
709
+ src=src,
710
+ dst=target_path,
711
+ strategy=MoveStrategy.COPY_VERIFY,
712
+ code=ErrorCode.PERMISSION,
713
+ message="copied but could not remove source",
714
+ created_dirs=tuple(created_dirs),
715
+ renamed_due_to_collision=(target_path.name != dst_name),
716
+ bytes_copied=size0,
717
+ )
718
+
719
+ # 10. fsync src's parent dir
720
+ self._fs.fsync_dir(src.parent)
721
+
722
+ renamed = target_path.name != dst_name
723
+ return MoveResult(
724
+ ok=True,
725
+ src=src,
726
+ dst=target_path,
727
+ strategy=MoveStrategy.COPY_VERIFY,
728
+ code=ErrorCode.NONE,
729
+ message="",
730
+ created_dirs=tuple(created_dirs),
731
+ renamed_due_to_collision=renamed,
732
+ bytes_copied=size0,
733
+ )
734
+
735
+ finally:
736
+ if not published and temp_path.exists():
737
+ with contextlib.suppress(OSError):
738
+ temp_path.unlink()
739
+
740
+
741
+ __all__ = ["SafeMover"]