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,196 @@
1
+ """Duplicate quarantine service for ClutterXP (v1.1).
2
+
3
+ Moves exact duplicates into a designated quarantine directory using Mover and History,
4
+ ensuring every operation is non-destructive, recorded in the journal, and undoable.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from collections.abc import Sequence
10
+ from dataclasses import dataclass
11
+ from pathlib import Path
12
+
13
+ from clutterxp import locking, paths, safety
14
+ from clutterxp.interfaces import History, Mover
15
+ from clutterxp.models import (
16
+ BatchResult,
17
+ CollisionPolicy,
18
+ CreateDestinations,
19
+ DuplicateGroup,
20
+ ErrorCode,
21
+ FileInfo,
22
+ MoveResult,
23
+ )
24
+
25
+
26
+ @dataclass(frozen=True, slots=True)
27
+ class QuarantineAction:
28
+ file: FileInfo
29
+ target_dir: Path
30
+ target_name: str
31
+ group_sha256: str | None
32
+
33
+
34
+ @dataclass(frozen=True, slots=True)
35
+ class QuarantinePlan:
36
+ quarantine_dir: Path
37
+ keep_strategy: str
38
+ kept_files: tuple[FileInfo, ...]
39
+ actions: tuple[QuarantineAction, ...]
40
+
41
+ @property
42
+ def total_moves(self) -> int:
43
+ return len(self.actions)
44
+
45
+ @property
46
+ def total_bytes(self) -> int:
47
+ return sum(a.file.size for a in self.actions)
48
+
49
+
50
+ def select_kept_file(
51
+ files: Sequence[FileInfo],
52
+ strategy: str,
53
+ keep_path: Path | None = None,
54
+ ) -> FileInfo:
55
+ """Select which file to keep according to strategy."""
56
+ if not files:
57
+ raise ValueError("Cannot select kept file from empty file list")
58
+
59
+ if keep_path is not None:
60
+ target_resolved = keep_path.resolve()
61
+ for f in files:
62
+ if f.path.resolve() == target_resolved:
63
+ return f
64
+ raise ValueError(f"keep_path '{keep_path}' is not present in duplicate group")
65
+
66
+ if strategy == "oldest":
67
+ return min(files, key=lambda f: (f.mtime_ns, str(f.path)))
68
+ elif strategy == "newest":
69
+ return max(files, key=lambda f: (f.mtime_ns, str(f.path)))
70
+ elif strategy == "shortest-path":
71
+ return min(files, key=lambda f: (len(str(f.path)), str(f.path)))
72
+ else:
73
+ raise ValueError(
74
+ f"Unknown keep strategy: {strategy!r}. "
75
+ "Must be 'oldest', 'newest', 'shortest-path', or specify keep_path."
76
+ )
77
+
78
+
79
+ def plan_quarantine(
80
+ groups: Sequence[DuplicateGroup],
81
+ quarantine_dir: Path,
82
+ *,
83
+ keep_strategy: str = "oldest",
84
+ keep_path: Path | None = None,
85
+ ) -> QuarantinePlan:
86
+ """Create a quarantine plan for exact duplicate groups."""
87
+ safety.check_destination(quarantine_dir / "test.tmp")
88
+
89
+ kept: list[FileInfo] = []
90
+ actions: list[QuarantineAction] = []
91
+
92
+ for group in groups:
93
+ if group.kind != "exact" or len(group.files) < 2:
94
+ continue
95
+
96
+ chosen_keep = select_kept_file(group.files, keep_strategy, keep_path=keep_path)
97
+ kept.append(chosen_keep)
98
+
99
+ for f in group.files:
100
+ if f == chosen_keep:
101
+ continue
102
+
103
+ actions.append(
104
+ QuarantineAction(
105
+ file=f,
106
+ target_dir=quarantine_dir,
107
+ target_name=f.name,
108
+ group_sha256=group.sha256,
109
+ )
110
+ )
111
+
112
+ return QuarantinePlan(
113
+ quarantine_dir=quarantine_dir,
114
+ keep_strategy=keep_strategy if keep_path is None else f"path:{keep_path}",
115
+ kept_files=tuple(kept),
116
+ actions=tuple(actions),
117
+ )
118
+
119
+
120
+ def apply_quarantine(
121
+ plan: QuarantinePlan,
122
+ mover: Mover,
123
+ history: History,
124
+ *,
125
+ fs_lock_path: Path | None = None,
126
+ ) -> BatchResult:
127
+ """Execute a quarantine plan under journal-first protocol and fs lock."""
128
+ lock_file = fs_lock_path if fs_lock_path is not None else paths.fs_lock_path()
129
+ batch_id = history.begin_batch("duplicates quarantine", folder=plan.quarantine_dir)
130
+
131
+ moved = 0
132
+ skipped = 0
133
+ blocked = 0
134
+ failed = 0
135
+ results: list[MoveResult] = []
136
+
137
+ with locking.fs_lock(lock_file):
138
+ for action in plan.actions:
139
+ # Check if source file vanished or changed
140
+ if not action.file.path.exists():
141
+ skipped += 1
142
+ res = MoveResult(
143
+ ok=False,
144
+ src=action.file.path,
145
+ dst=None,
146
+ strategy=None,
147
+ code=ErrorCode.SRC_VANISHED,
148
+ message="File vanished before quarantine",
149
+ )
150
+ results.append(res)
151
+ continue
152
+
153
+ # Record durable pending op in journal before move (Invariant S5)
154
+ op_id = history.begin_op(
155
+ batch_id,
156
+ action.file.path,
157
+ "quarantine",
158
+ action.file,
159
+ )
160
+
161
+ # Move file using SafeMover (rename on collision, create dir)
162
+ res = mover.move_file(
163
+ action.file.path,
164
+ action.target_dir,
165
+ new_name=action.target_name,
166
+ collision=CollisionPolicy.RENAME,
167
+ create=CreateDestinations.ALL,
168
+ expect_size=action.file.size,
169
+ expect_mtime_ns=action.file.mtime_ns,
170
+ )
171
+
172
+ history.finish_op(op_id, res)
173
+ results.append(res)
174
+
175
+ if res.ok:
176
+ moved += 1
177
+ else:
178
+ failed += 1
179
+
180
+ return BatchResult(
181
+ batch_id=batch_id,
182
+ moved=moved,
183
+ skipped=skipped,
184
+ blocked=blocked,
185
+ failed=failed,
186
+ results=tuple(results),
187
+ )
188
+
189
+
190
+ __all__ = [
191
+ "QuarantineAction",
192
+ "QuarantinePlan",
193
+ "apply_quarantine",
194
+ "plan_quarantine",
195
+ "select_kept_file",
196
+ ]
@@ -0,0 +1,110 @@
1
+ """Serializers for duplicate groups (JSON and CSV formats)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Sequence
6
+ from pathlib import Path
7
+ from typing import Any
8
+
9
+ from clutterxp.models import DuplicateGroup
10
+
11
+
12
+ def groups_to_json(
13
+ groups: Sequence[DuplicateGroup],
14
+ folders: Sequence[Path],
15
+ file_count: int,
16
+ total_bytes: int,
17
+ ) -> dict[str, Any]:
18
+ """Returns the JSON shape from docs/07 section 4."""
19
+ exact_list: list[dict[str, Any]] = []
20
+ hardlinks_list: list[dict[str, Any]] = []
21
+ potential_list: list[dict[str, Any]] = []
22
+
23
+ exact_groups_count = 0
24
+ total_wasted_bytes = 0
25
+ potential_groups_count = 0
26
+
27
+ for g in groups:
28
+ if g.kind == "exact":
29
+ exact_groups_count += 1
30
+ total_wasted_bytes += g.wasted_bytes
31
+ exact_list.append(
32
+ {
33
+ "sha256": g.sha256 or "",
34
+ "size": g.files[0].size if g.files else 0,
35
+ "wasted_bytes": g.wasted_bytes,
36
+ "files": [
37
+ {
38
+ "path": str(f.path),
39
+ "mtime_ns": f.mtime_ns,
40
+ "inode": f.inode,
41
+ }
42
+ for f in g.files
43
+ ],
44
+ }
45
+ )
46
+ elif g.kind == "hardlink":
47
+ hardlinks_list.append(
48
+ {
49
+ "files": [str(f.path) for f in g.files],
50
+ }
51
+ )
52
+ elif g.kind == "potential":
53
+ potential_groups_count += 1
54
+ potential_list.append(
55
+ {
56
+ "note": g.note,
57
+ "files": [str(f.path) for f in g.files],
58
+ }
59
+ )
60
+
61
+ return {
62
+ "schema_version": 1,
63
+ "scanned": {
64
+ "folders": [str(p) for p in folders],
65
+ "files": file_count,
66
+ "bytes": total_bytes,
67
+ },
68
+ "exact": exact_list,
69
+ "hardlinks": hardlinks_list,
70
+ "potential": potential_list,
71
+ "summary": {
72
+ "exact_groups": exact_groups_count,
73
+ "wasted_bytes": total_wasted_bytes,
74
+ "potential_groups": potential_groups_count,
75
+ },
76
+ }
77
+
78
+
79
+ def groups_to_csv_rows(groups: Sequence[DuplicateGroup]) -> list[list[str]]:
80
+ """Returns [header_row, data_rows...] for CSV output."""
81
+ header = [
82
+ "group_id",
83
+ "kind",
84
+ "sha256",
85
+ "size",
86
+ "wasted_bytes",
87
+ "note",
88
+ "path",
89
+ "mtime_ns",
90
+ "inode",
91
+ ]
92
+ rows: list[list[str]] = [header]
93
+
94
+ for idx, g in enumerate(groups, start=1):
95
+ for f in g.files:
96
+ rows.append(
97
+ [
98
+ str(idx),
99
+ g.kind,
100
+ g.sha256 or "",
101
+ str(f.size),
102
+ str(g.wasted_bytes),
103
+ g.note,
104
+ str(f.path),
105
+ str(f.mtime_ns),
106
+ str(f.inode),
107
+ ]
108
+ )
109
+
110
+ return rows
@@ -0,0 +1 @@
1
+ """Graphical user interface (PySide6)."""