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.
- clutterxp/__init__.py +4 -0
- clutterxp/cli/__init__.py +7 -0
- clutterxp/cli/app.py +251 -0
- clutterxp/cli/cmd_config.py +250 -0
- clutterxp/cli/cmd_doctor.py +449 -0
- clutterxp/cli/cmd_duplicates.py +253 -0
- clutterxp/cli/cmd_gui.py +22 -0
- clutterxp/cli/cmd_history.py +233 -0
- clutterxp/cli/cmd_init.py +76 -0
- clutterxp/cli/cmd_organize.py +226 -0
- clutterxp/cli/cmd_rules.py +540 -0
- clutterxp/cli/cmd_scan.py +109 -0
- clutterxp/cli/cmd_service.py +130 -0
- clutterxp/cli/cmd_undo.py +180 -0
- clutterxp/cli/cmd_watch.py +147 -0
- clutterxp/cli/errors.py +166 -0
- clutterxp/cli/render.py +390 -0
- clutterxp/config/__init__.py +40 -0
- clutterxp/config/jsonschema.py +12 -0
- clutterxp/config/loader.py +212 -0
- clutterxp/config/placeholders.py +79 -0
- clutterxp/config/runtime.py +30 -0
- clutterxp/config/schema.py +166 -0
- clutterxp/config/validate.py +226 -0
- clutterxp/config/writer.py +248 -0
- clutterxp/config.example.yaml +76 -0
- clutterxp/duplicates/__init__.py +22 -0
- clutterxp/duplicates/detector.py +438 -0
- clutterxp/duplicates/hashcache.py +149 -0
- clutterxp/duplicates/namenorm.py +45 -0
- clutterxp/duplicates/quarantine.py +196 -0
- clutterxp/duplicates/report.py +110 -0
- clutterxp/gui/__init__.py +1 -0
- clutterxp/gui/api.py +494 -0
- clutterxp/gui/app.py +205 -0
- clutterxp/gui/models_qt.py +544 -0
- clutterxp/gui/views/__init__.py +21 -0
- clutterxp/gui/views/dashboard.py +253 -0
- clutterxp/gui/views/duplicates.py +404 -0
- clutterxp/gui/views/folders.py +354 -0
- clutterxp/gui/views/history.py +281 -0
- clutterxp/gui/views/preview.py +277 -0
- clutterxp/gui/views/rules.py +527 -0
- clutterxp/gui/views/settings.py +172 -0
- clutterxp/gui/workers.py +147 -0
- clutterxp/history/__init__.py +23 -0
- clutterxp/history/db.py +174 -0
- clutterxp/history/pathcodec.py +42 -0
- clutterxp/history/recovery.py +318 -0
- clutterxp/history/schema.sql +43 -0
- clutterxp/history/service.py +493 -0
- clutterxp/history/undo.py +373 -0
- clutterxp/interfaces.py +164 -0
- clutterxp/locking.py +113 -0
- clutterxp/logging_setup.py +73 -0
- clutterxp/models.py +266 -0
- clutterxp/mover/__init__.py +26 -0
- clutterxp/mover/collision.py +46 -0
- clutterxp/mover/fsops.py +191 -0
- clutterxp/mover/safe_move.py +741 -0
- clutterxp/organizer.py +388 -0
- clutterxp/packaging/clutterxp.service +15 -0
- clutterxp/paths.py +112 -0
- clutterxp/planner.py +339 -0
- clutterxp/py.typed +0 -0
- clutterxp/rules/__init__.py +16 -0
- clutterxp/rules/engine.py +374 -0
- clutterxp/rules/matcher.py +222 -0
- clutterxp/rules/template.py +171 -0
- clutterxp/rules/tokenizer.py +118 -0
- clutterxp/safety.py +111 -0
- clutterxp/scanner.py +196 -0
- clutterxp/service_install.py +208 -0
- clutterxp/units.py +59 -0
- clutterxp/watch/__init__.py +37 -0
- clutterxp/watch/debounce.py +84 -0
- clutterxp/watch/events.py +259 -0
- clutterxp/watch/ignore.py +77 -0
- clutterxp/watch/service.py +662 -0
- clutterxp/watch/settle.py +170 -0
- clutterxp-1.1.0.dist-info/METADATA +149 -0
- clutterxp-1.1.0.dist-info/RECORD +84 -0
- clutterxp-1.1.0.dist-info/WHEEL +4 -0
- clutterxp-1.1.0.dist-info/entry_points.txt +6 -0
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
"""Logging configuration with rotating file handler and stderr verbosity."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import contextlib
|
|
6
|
+
import logging
|
|
7
|
+
import os
|
|
8
|
+
import sys
|
|
9
|
+
from logging.handlers import RotatingFileHandler
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
from typing import Any, cast
|
|
12
|
+
|
|
13
|
+
from .paths import _ensure_dir_0700, log_path
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class SafeRotatingFileHandler(RotatingFileHandler):
|
|
17
|
+
"""RotatingFileHandler that creates files with 0600 permissions."""
|
|
18
|
+
|
|
19
|
+
def _open(self) -> Any:
|
|
20
|
+
flags = os.O_CREAT | os.O_WRONLY | os.O_APPEND
|
|
21
|
+
fd = os.open(self.baseFilename, flags, 0o600)
|
|
22
|
+
with contextlib.suppress(OSError):
|
|
23
|
+
Path(self.baseFilename).chmod(0o600)
|
|
24
|
+
return cast(Any, open(fd, mode=self.mode, encoding=self.encoding)) # noqa: PTH123
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def setup_logging(verbosity: int = 0, log_file: Path | None = None) -> None:
|
|
28
|
+
"""Set up logging for the clutterxp package.
|
|
29
|
+
|
|
30
|
+
Args:
|
|
31
|
+
verbosity: 0 = WARNING, 1 = INFO, >= 2 = DEBUG on stderr.
|
|
32
|
+
log_file: Path to rotating log file. Defaults to paths.log_path().
|
|
33
|
+
"""
|
|
34
|
+
target_log = log_file if log_file is not None else log_path()
|
|
35
|
+
_ensure_dir_0700(target_log.parent)
|
|
36
|
+
|
|
37
|
+
logger = logging.getLogger("clutterxp")
|
|
38
|
+
logger.setLevel(logging.DEBUG)
|
|
39
|
+
logger.propagate = False
|
|
40
|
+
|
|
41
|
+
# Clear previous handlers to avoid duplicate log records
|
|
42
|
+
for h in list(logger.handlers):
|
|
43
|
+
logger.removeHandler(h)
|
|
44
|
+
h.close()
|
|
45
|
+
|
|
46
|
+
# 1. Stderr handler
|
|
47
|
+
if verbosity >= 2:
|
|
48
|
+
stderr_level = logging.DEBUG
|
|
49
|
+
stderr_fmt = "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
|
|
50
|
+
elif verbosity == 1:
|
|
51
|
+
stderr_level = logging.INFO
|
|
52
|
+
stderr_fmt = "%(levelname)s: %(message)s"
|
|
53
|
+
else:
|
|
54
|
+
stderr_level = logging.WARNING
|
|
55
|
+
stderr_fmt = "%(levelname)s: %(message)s"
|
|
56
|
+
|
|
57
|
+
stderr_handler = logging.StreamHandler(sys.stderr)
|
|
58
|
+
stderr_handler.setLevel(stderr_level)
|
|
59
|
+
stderr_handler.setFormatter(logging.Formatter(stderr_fmt))
|
|
60
|
+
logger.addHandler(stderr_handler)
|
|
61
|
+
|
|
62
|
+
# 2. Rotating file handler (5 x 1 MB)
|
|
63
|
+
file_handler = SafeRotatingFileHandler(
|
|
64
|
+
str(target_log),
|
|
65
|
+
maxBytes=1_000_000,
|
|
66
|
+
backupCount=5,
|
|
67
|
+
encoding="utf-8",
|
|
68
|
+
)
|
|
69
|
+
file_handler.setLevel(logging.DEBUG)
|
|
70
|
+
file_handler.setFormatter(
|
|
71
|
+
logging.Formatter("%(asctime)s [%(levelname)s] %(name)s: %(message)s")
|
|
72
|
+
)
|
|
73
|
+
logger.addHandler(file_handler)
|
clutterxp/models.py
ADDED
|
@@ -0,0 +1,266 @@
|
|
|
1
|
+
"""ClutterXP shared contracts (FROZEN).
|
|
2
|
+
|
|
3
|
+
Every module imports its data types, enums and exceptions from this file.
|
|
4
|
+
Changing anything here requires a CONTRACT_CHANGE request (see AGENTS.md).
|
|
5
|
+
|
|
6
|
+
Design rules:
|
|
7
|
+
* Plain frozen dataclasses, no business logic.
|
|
8
|
+
* Paths are pathlib.Path; never str.
|
|
9
|
+
* Times are integer nanoseconds (st_mtime_ns) for exact comparison.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import stat
|
|
15
|
+
from dataclasses import dataclass
|
|
16
|
+
from enum import Enum
|
|
17
|
+
from pathlib import Path
|
|
18
|
+
from typing import Callable
|
|
19
|
+
|
|
20
|
+
SCHEMA_VERSION = 1 # JSON output schema version and config schema version
|
|
21
|
+
|
|
22
|
+
# (bytes_done, bytes_total) - called during slow operations (copy, hashing)
|
|
23
|
+
ProgressCb = Callable[[int, int], None]
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
# --------------------------------------------------------------------------- enums
|
|
27
|
+
class MatchMode(str, Enum):
|
|
28
|
+
TOKEN = "token" # default: keyword must equal whole filename token(s)
|
|
29
|
+
PREFIX = "prefix" # a filename token starts with the keyword
|
|
30
|
+
SUBSTRING = "substring" # keyword anywhere in the casefolded stem
|
|
31
|
+
GLOB = "glob" # fnmatch against the full filename
|
|
32
|
+
REGEX = "regex" # re.search against the full filename
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class CollisionPolicy(str, Enum):
|
|
36
|
+
SKIP = "skip" # leave the file where it is, report BLOCKED/COLLISION
|
|
37
|
+
RENAME = "rename" # add " (1)", " (2)", ... before the extension
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
class CreateDestinations(str, Enum):
|
|
41
|
+
NEVER = "never" # destination must already exist
|
|
42
|
+
LEAF = (
|
|
43
|
+
"leaf" # create last component of the static root (parent must exist) + templated subdirs
|
|
44
|
+
)
|
|
45
|
+
ALL = "all" # mkdir -p
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
class DecisionKind(str, Enum):
|
|
49
|
+
MATCH = "match"
|
|
50
|
+
NO_MATCH = "no_match"
|
|
51
|
+
AMBIGUOUS = "ambiguous"
|
|
52
|
+
IGNORED = "ignored" # hidden / temp / ignore-pattern / not a regular file
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
class PlanStatus(str, Enum):
|
|
56
|
+
WILL_MOVE = "will_move"
|
|
57
|
+
WILL_MOVE_RENAMED = "will_move_renamed"
|
|
58
|
+
NO_MATCH = "no_match"
|
|
59
|
+
AMBIGUOUS = "ambiguous"
|
|
60
|
+
IGNORED = "ignored"
|
|
61
|
+
BLOCKED = "blocked" # see ErrorCode
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
class OpStatus(str, Enum):
|
|
65
|
+
PENDING = "pending"
|
|
66
|
+
DONE = "done"
|
|
67
|
+
UNDONE = "undone"
|
|
68
|
+
FAILED = "failed"
|
|
69
|
+
SKIPPED = "skipped"
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
class MoveStrategy(str, Enum):
|
|
73
|
+
RENAME_NOREPLACE = "renameat2" # renameat2(RENAME_NOREPLACE), one atomic syscall
|
|
74
|
+
LINK_UNLINK = "link_unlink" # os.link (fails if exists) then os.unlink(src)
|
|
75
|
+
CHECKED_RENAME = "checked_rename" # lock-protected exists-check + os.rename (last resort)
|
|
76
|
+
COPY_VERIFY = "copy_verify" # cross-filesystem: temp copy, fsync, verify, publish, unlink src
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
class ErrorCode(str, Enum):
|
|
80
|
+
NONE = "none"
|
|
81
|
+
COLLISION = "collision"
|
|
82
|
+
DEST_MISSING = "dest_missing"
|
|
83
|
+
DEST_NOT_WRITABLE = "dest_not_writable"
|
|
84
|
+
DEST_INVALID = "dest_invalid" # inside watched folder, system dir, traversal, etc.
|
|
85
|
+
SRC_VANISHED = "src_vanished"
|
|
86
|
+
SRC_CHANGED = "src_changed" # size/mtime changed during the operation
|
|
87
|
+
SRC_NOT_REGULAR = "src_not_regular" # directory, symlink, device, socket...
|
|
88
|
+
PERMISSION = "permission"
|
|
89
|
+
NO_SPACE = "no_space"
|
|
90
|
+
VERIFY_FAILED = "verify_failed"
|
|
91
|
+
LOCK_TIMEOUT = "lock_timeout"
|
|
92
|
+
UNDO_NOT_DONE = "undo_not_done"
|
|
93
|
+
UNDO_DEST_CHANGED = "undo_dest_changed"
|
|
94
|
+
UNDO_ORIGIN_OCCUPIED = "undo_origin_occupied"
|
|
95
|
+
UNDO_DEST_MISSING = "undo_dest_missing"
|
|
96
|
+
UNKNOWN = "unknown"
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
# --------------------------------------------------------------------------- errors
|
|
100
|
+
class ClutterError(Exception):
|
|
101
|
+
"""Base class for all expected, user-reportable errors."""
|
|
102
|
+
|
|
103
|
+
def __init__(self, message: str, code: ErrorCode = ErrorCode.UNKNOWN) -> None:
|
|
104
|
+
super().__init__(message)
|
|
105
|
+
self.message = message
|
|
106
|
+
self.code = code
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
class ConfigError(ClutterError):
|
|
110
|
+
"""Invalid configuration. `problems` holds one human-readable line per issue."""
|
|
111
|
+
|
|
112
|
+
def __init__(self, message: str, problems: tuple[str, ...] = ()) -> None:
|
|
113
|
+
super().__init__(message, ErrorCode.UNKNOWN)
|
|
114
|
+
self.problems = problems
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
class SafetyRefusal(ClutterError):
|
|
118
|
+
"""Operation refused by a safety invariant (root user, system directory, ...)."""
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
# --------------------------------------------------------------------------- file + rules
|
|
122
|
+
@dataclass(frozen=True, slots=True)
|
|
123
|
+
class FileInfo:
|
|
124
|
+
path: Path
|
|
125
|
+
name: str
|
|
126
|
+
stem: str
|
|
127
|
+
ext: str # last suffix, lowercase, no dot; "" if none
|
|
128
|
+
size: int
|
|
129
|
+
mtime_ns: int
|
|
130
|
+
inode: int
|
|
131
|
+
device: int
|
|
132
|
+
is_regular: bool = True
|
|
133
|
+
is_symlink: bool = False
|
|
134
|
+
|
|
135
|
+
@classmethod
|
|
136
|
+
def from_path(cls, path: Path | str) -> "FileInfo":
|
|
137
|
+
p = Path(path)
|
|
138
|
+
st = p.lstat()
|
|
139
|
+
suffix = p.suffix
|
|
140
|
+
return cls(
|
|
141
|
+
path=p,
|
|
142
|
+
name=p.name,
|
|
143
|
+
stem=p.stem,
|
|
144
|
+
ext=suffix[1:].lower() if suffix else "",
|
|
145
|
+
size=st.st_size,
|
|
146
|
+
mtime_ns=st.st_mtime_ns,
|
|
147
|
+
inode=st.st_ino,
|
|
148
|
+
device=st.st_dev,
|
|
149
|
+
is_regular=stat.S_ISREG(st.st_mode),
|
|
150
|
+
is_symlink=stat.S_ISLNK(st.st_mode),
|
|
151
|
+
)
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
@dataclass(frozen=True, slots=True)
|
|
155
|
+
class RuleHit:
|
|
156
|
+
rule_name: str
|
|
157
|
+
priority: int
|
|
158
|
+
dest_dir: Path # fully expanded (~, $VARS, templates) destination directory
|
|
159
|
+
static_root: Path # dest path up to the first template placeholder
|
|
160
|
+
matched_by: str # human text, e.g. "keyword 'sl' (token)"
|
|
161
|
+
collision: CollisionPolicy
|
|
162
|
+
create: CreateDestinations
|
|
163
|
+
also_matched: tuple[str, ...] = () # lower-priority / same-destination rules that also matched
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
@dataclass(frozen=True, slots=True)
|
|
167
|
+
class Decision:
|
|
168
|
+
file: FileInfo
|
|
169
|
+
kind: DecisionKind
|
|
170
|
+
hit: RuleHit | None = None
|
|
171
|
+
candidates: tuple[RuleHit, ...] = () # populated when kind == AMBIGUOUS
|
|
172
|
+
reason: str = "" # populated for NO_MATCH / IGNORED
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
@dataclass(frozen=True, slots=True)
|
|
176
|
+
class RuleTrace:
|
|
177
|
+
"""One line of `rules test` output: why a rule did or did not match."""
|
|
178
|
+
|
|
179
|
+
rule_name: str
|
|
180
|
+
matched: bool
|
|
181
|
+
priority: int
|
|
182
|
+
reasons: tuple[str, ...]
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
# --------------------------------------------------------------------------- planning + moving
|
|
186
|
+
@dataclass(frozen=True, slots=True)
|
|
187
|
+
class PlannedAction:
|
|
188
|
+
file: FileInfo
|
|
189
|
+
status: PlanStatus
|
|
190
|
+
decision: Decision
|
|
191
|
+
dest_path: Path | None = None
|
|
192
|
+
code: ErrorCode = ErrorCode.NONE
|
|
193
|
+
message: str = ""
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
@dataclass(frozen=True, slots=True)
|
|
197
|
+
class Plan:
|
|
198
|
+
folders: tuple[Path, ...]
|
|
199
|
+
actions: tuple[PlannedAction, ...]
|
|
200
|
+
|
|
201
|
+
def count(self, status: PlanStatus) -> int:
|
|
202
|
+
return sum(1 for a in self.actions if a.status is status)
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
@dataclass(frozen=True, slots=True)
|
|
206
|
+
class MoveResult:
|
|
207
|
+
ok: bool
|
|
208
|
+
src: Path
|
|
209
|
+
dst: Path | None
|
|
210
|
+
strategy: MoveStrategy | None
|
|
211
|
+
code: ErrorCode = ErrorCode.NONE
|
|
212
|
+
message: str = ""
|
|
213
|
+
created_dirs: tuple[Path, ...] = ()
|
|
214
|
+
renamed_due_to_collision: bool = False
|
|
215
|
+
bytes_copied: int = 0
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
# --------------------------------------------------------------------------- history + undo
|
|
219
|
+
@dataclass(frozen=True, slots=True)
|
|
220
|
+
class OperationRecord:
|
|
221
|
+
id: int
|
|
222
|
+
batch_id: int
|
|
223
|
+
status: OpStatus
|
|
224
|
+
src_path: Path
|
|
225
|
+
dst_path: Path | None
|
|
226
|
+
rule_name: str | None
|
|
227
|
+
strategy: MoveStrategy | None
|
|
228
|
+
size: int | None
|
|
229
|
+
mtime_ns: int | None
|
|
230
|
+
inode: int | None
|
|
231
|
+
device: int | None
|
|
232
|
+
sha256: str | None
|
|
233
|
+
created_dirs: tuple[Path, ...]
|
|
234
|
+
created_at: str # ISO-8601 UTC
|
|
235
|
+
finished_at: str | None
|
|
236
|
+
undone_at: str | None
|
|
237
|
+
error: str | None
|
|
238
|
+
|
|
239
|
+
|
|
240
|
+
@dataclass(frozen=True, slots=True)
|
|
241
|
+
class UndoOutcome:
|
|
242
|
+
op_id: int
|
|
243
|
+
ok: bool
|
|
244
|
+
restored_to: Path | None = None
|
|
245
|
+
code: ErrorCode = ErrorCode.NONE
|
|
246
|
+
message: str = ""
|
|
247
|
+
|
|
248
|
+
|
|
249
|
+
@dataclass(frozen=True, slots=True)
|
|
250
|
+
class BatchResult:
|
|
251
|
+
batch_id: int | None
|
|
252
|
+
moved: int
|
|
253
|
+
skipped: int
|
|
254
|
+
blocked: int
|
|
255
|
+
failed: int
|
|
256
|
+
results: tuple[MoveResult, ...] = ()
|
|
257
|
+
|
|
258
|
+
|
|
259
|
+
# --------------------------------------------------------------------------- duplicates
|
|
260
|
+
@dataclass(frozen=True, slots=True)
|
|
261
|
+
class DuplicateGroup:
|
|
262
|
+
kind: str # "exact" | "potential" | "hardlink"
|
|
263
|
+
files: tuple[FileInfo, ...]
|
|
264
|
+
sha256: str | None = None # set for kind == "exact"
|
|
265
|
+
wasted_bytes: int = 0 # (n-1) * size for exact groups, 0 otherwise
|
|
266
|
+
note: str = "" # e.g. why files are "potential" candidates
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
"""Safe mover: atomic operations, collision handling, and verification."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from clutterxp.mover.collision import candidate_names, split_name_ext
|
|
6
|
+
from clutterxp.mover.fsops import (
|
|
7
|
+
checked_rename,
|
|
8
|
+
fsync_dir,
|
|
9
|
+
fsync_file,
|
|
10
|
+
link_unlink,
|
|
11
|
+
rename_noreplace,
|
|
12
|
+
same_device,
|
|
13
|
+
)
|
|
14
|
+
from clutterxp.mover.safe_move import SafeMover
|
|
15
|
+
|
|
16
|
+
__all__ = [
|
|
17
|
+
"SafeMover",
|
|
18
|
+
"candidate_names",
|
|
19
|
+
"checked_rename",
|
|
20
|
+
"fsync_dir",
|
|
21
|
+
"fsync_file",
|
|
22
|
+
"link_unlink",
|
|
23
|
+
"rename_noreplace",
|
|
24
|
+
"same_device",
|
|
25
|
+
"split_name_ext",
|
|
26
|
+
]
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
"""Collision candidate generator for rename policies."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from collections.abc import Generator
|
|
6
|
+
|
|
7
|
+
COMPOUND_EXTS: tuple[str, ...] = (
|
|
8
|
+
".tar.gz",
|
|
9
|
+
".tar.bz2",
|
|
10
|
+
".tar.xz",
|
|
11
|
+
".tar.zst",
|
|
12
|
+
)
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def split_name_ext(name: str) -> tuple[str, str]:
|
|
16
|
+
"""Split filename into stem and extension, preserving compound extensions.
|
|
17
|
+
|
|
18
|
+
Compound extensions like .tar.gz are treated as a single extension.
|
|
19
|
+
For names with multiple dots like report.2024.pdf, only the last extension is split.
|
|
20
|
+
Leading dots (e.g. .gitignore) are treated as part of the stem unless there is
|
|
21
|
+
another dot (e.g. .bashrc.bak).
|
|
22
|
+
"""
|
|
23
|
+
lower_name = name.lower()
|
|
24
|
+
for compound in COMPOUND_EXTS:
|
|
25
|
+
if lower_name.endswith(compound) and len(name) > len(compound):
|
|
26
|
+
return name[: -len(compound)], name[-len(compound) :]
|
|
27
|
+
|
|
28
|
+
dot_index = name.rfind(".")
|
|
29
|
+
if dot_index > 0: # Dot is not the first character
|
|
30
|
+
return name[:dot_index], name[dot_index:]
|
|
31
|
+
return name, ""
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def candidate_names(name: str) -> Generator[str, None, None]:
|
|
35
|
+
"""Yield name (1).ext, name (2).ext, ... up to 9999.
|
|
36
|
+
|
|
37
|
+
Handles compound extensions (.tar.gz): stem is everything before .tar.gz.
|
|
38
|
+
Handles no-extension names.
|
|
39
|
+
name (1).ext format: space before parens.
|
|
40
|
+
"""
|
|
41
|
+
stem, ext = split_name_ext(name)
|
|
42
|
+
for i in range(1, 10000):
|
|
43
|
+
yield f"{stem} ({i}){ext}"
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
__all__ = ["COMPOUND_EXTS", "candidate_names", "split_name_ext"]
|
clutterxp/mover/fsops.py
ADDED
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
"""Low-level filesystem operations with atomic no-clobber primitives."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import ctypes
|
|
6
|
+
import errno
|
|
7
|
+
import logging
|
|
8
|
+
import os
|
|
9
|
+
import threading
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
|
|
12
|
+
logger = logging.getLogger(__name__)
|
|
13
|
+
|
|
14
|
+
# renameat2 constants (from linux/fs.h and fcntl.h)
|
|
15
|
+
AT_FDCWD = -100
|
|
16
|
+
RENAME_NOREPLACE = 1
|
|
17
|
+
|
|
18
|
+
_capability_cache: dict[str, bool] = {}
|
|
19
|
+
_capability_lock = threading.Lock()
|
|
20
|
+
_checked_rename_lock = threading.Lock()
|
|
21
|
+
|
|
22
|
+
# Load libc
|
|
23
|
+
_libc: ctypes.CDLL | None = None
|
|
24
|
+
try:
|
|
25
|
+
_libc = ctypes.CDLL(None, use_errno=True)
|
|
26
|
+
if hasattr(_libc, "renameat2"):
|
|
27
|
+
_libc.renameat2.argtypes = [
|
|
28
|
+
ctypes.c_int,
|
|
29
|
+
ctypes.c_char_p,
|
|
30
|
+
ctypes.c_int,
|
|
31
|
+
ctypes.c_char_p,
|
|
32
|
+
ctypes.c_uint,
|
|
33
|
+
]
|
|
34
|
+
_libc.renameat2.restype = ctypes.c_int
|
|
35
|
+
else:
|
|
36
|
+
_capability_cache["renameat2"] = False
|
|
37
|
+
except Exception:
|
|
38
|
+
_capability_cache["renameat2"] = False
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def rename_noreplace(src: Path, dst: Path) -> bool:
|
|
42
|
+
"""Attempt renameat2(RENAME_NOREPLACE). Returns True on success.
|
|
43
|
+
|
|
44
|
+
Returns False if EEXIST/ENOTSUP/EPERM (caller tries next strategy).
|
|
45
|
+
Uses _capability_cache after first failure of this call.
|
|
46
|
+
"""
|
|
47
|
+
with _capability_lock:
|
|
48
|
+
if _capability_cache.get("renameat2") is False:
|
|
49
|
+
return False
|
|
50
|
+
|
|
51
|
+
if _libc is None or not hasattr(_libc, "renameat2"):
|
|
52
|
+
with _capability_lock:
|
|
53
|
+
_capability_cache["renameat2"] = False
|
|
54
|
+
return False
|
|
55
|
+
|
|
56
|
+
src_bytes = os.fsencode(src)
|
|
57
|
+
dst_bytes = os.fsencode(dst)
|
|
58
|
+
|
|
59
|
+
res = _libc.renameat2(AT_FDCWD, src_bytes, AT_FDCWD, dst_bytes, RENAME_NOREPLACE)
|
|
60
|
+
if res == 0:
|
|
61
|
+
with _capability_lock:
|
|
62
|
+
_capability_cache["renameat2"] = True
|
|
63
|
+
return True
|
|
64
|
+
|
|
65
|
+
err = ctypes.get_errno()
|
|
66
|
+
if err == errno.EEXIST:
|
|
67
|
+
# Destination exists. Syscall is supported!
|
|
68
|
+
with _capability_lock:
|
|
69
|
+
_capability_cache["renameat2"] = True
|
|
70
|
+
return False
|
|
71
|
+
elif err in (errno.ENOSYS, errno.ENOTSUP, errno.EOPNOTSUPP, errno.EINVAL, errno.EPERM):
|
|
72
|
+
# Syscall or flag not supported on this kernel/filesystem
|
|
73
|
+
with _capability_lock:
|
|
74
|
+
_capability_cache["renameat2"] = False
|
|
75
|
+
return False
|
|
76
|
+
elif err == errno.EXDEV:
|
|
77
|
+
raise OSError(errno.EXDEV, os.strerror(errno.EXDEV), str(src))
|
|
78
|
+
else:
|
|
79
|
+
raise OSError(err, os.strerror(err), str(src))
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def link_unlink(src: Path, dst: Path) -> bool:
|
|
83
|
+
"""os.link(src, dst) [fails if dst exists], then os.unlink(src).
|
|
84
|
+
|
|
85
|
+
If unlink fails after successful link: log warning but do NOT delete dst (data safety).
|
|
86
|
+
Returns True on success.
|
|
87
|
+
"""
|
|
88
|
+
with _capability_lock:
|
|
89
|
+
if _capability_cache.get("link") is False:
|
|
90
|
+
return False
|
|
91
|
+
|
|
92
|
+
try:
|
|
93
|
+
os.link(src, dst, follow_symlinks=False)
|
|
94
|
+
except (FileExistsError, OSError) as err:
|
|
95
|
+
if isinstance(err, FileExistsError) or err.errno == errno.EEXIST:
|
|
96
|
+
with _capability_lock:
|
|
97
|
+
_capability_cache["link"] = True
|
|
98
|
+
return False
|
|
99
|
+
elif err.errno in (errno.ENOTSUP, errno.EOPNOTSUPP, errno.EPERM):
|
|
100
|
+
with _capability_lock:
|
|
101
|
+
_capability_cache["link"] = False
|
|
102
|
+
return False
|
|
103
|
+
elif err.errno == errno.EXDEV:
|
|
104
|
+
raise
|
|
105
|
+
else:
|
|
106
|
+
raise
|
|
107
|
+
|
|
108
|
+
with _capability_lock:
|
|
109
|
+
_capability_cache["link"] = True
|
|
110
|
+
|
|
111
|
+
try:
|
|
112
|
+
src.unlink()
|
|
113
|
+
except OSError as err:
|
|
114
|
+
logger.warning(
|
|
115
|
+
"Failed to unlink source '%s' after link to '%s': %s (kept for safety)",
|
|
116
|
+
src,
|
|
117
|
+
dst,
|
|
118
|
+
err,
|
|
119
|
+
)
|
|
120
|
+
return False
|
|
121
|
+
|
|
122
|
+
return True
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
def checked_rename(src: Path, dst: Path) -> bool:
|
|
126
|
+
"""Under a per-process lock: check dst does not exist, then os.rename.
|
|
127
|
+
|
|
128
|
+
Returns True on success. This is a last resort (not atomic, but protected within process).
|
|
129
|
+
"""
|
|
130
|
+
with _checked_rename_lock:
|
|
131
|
+
if os.path.lexists(dst):
|
|
132
|
+
return False
|
|
133
|
+
try:
|
|
134
|
+
src.rename(dst)
|
|
135
|
+
return True
|
|
136
|
+
except (FileExistsError, OSError) as e:
|
|
137
|
+
if isinstance(e, FileExistsError) or e.errno == errno.EEXIST:
|
|
138
|
+
return False
|
|
139
|
+
raise
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def _dev_of(p: Path) -> int:
|
|
143
|
+
curr = p
|
|
144
|
+
while not curr.exists() and curr != curr.parent:
|
|
145
|
+
curr = curr.parent
|
|
146
|
+
return curr.stat().st_dev
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
def same_device(a: Path, b: Path) -> bool:
|
|
150
|
+
"""True if a and b are on the same filesystem (st_dev comparison)."""
|
|
151
|
+
return _dev_of(a) == _dev_of(b)
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
def fsync_file(path: Path) -> None:
|
|
155
|
+
"""Open file and fsync, then close."""
|
|
156
|
+
fd = os.open(path, os.O_RDONLY)
|
|
157
|
+
try:
|
|
158
|
+
os.fsync(fd)
|
|
159
|
+
finally:
|
|
160
|
+
os.close(fd)
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def fsync_dir(path: Path) -> None:
|
|
164
|
+
"""Open directory and fsync."""
|
|
165
|
+
flags = os.O_RDONLY
|
|
166
|
+
if hasattr(os, "O_DIRECTORY"):
|
|
167
|
+
flags |= os.O_DIRECTORY
|
|
168
|
+
try:
|
|
169
|
+
fd = os.open(path, flags)
|
|
170
|
+
except OSError:
|
|
171
|
+
return
|
|
172
|
+
try:
|
|
173
|
+
os.fsync(fd)
|
|
174
|
+
except OSError as e:
|
|
175
|
+
if e.errno not in (errno.EINVAL, errno.ENOTSUP, errno.EOPNOTSUPP, errno.EPERM):
|
|
176
|
+
raise
|
|
177
|
+
finally:
|
|
178
|
+
os.close(fd)
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
__all__ = [
|
|
182
|
+
"AT_FDCWD",
|
|
183
|
+
"RENAME_NOREPLACE",
|
|
184
|
+
"_capability_cache",
|
|
185
|
+
"checked_rename",
|
|
186
|
+
"fsync_dir",
|
|
187
|
+
"fsync_file",
|
|
188
|
+
"link_unlink",
|
|
189
|
+
"rename_noreplace",
|
|
190
|
+
"same_device",
|
|
191
|
+
]
|