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,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"]
@@ -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
+ ]