dazzle-filekit 0.2.4__tar.gz → 0.3.0__tar.gz

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 (44) hide show
  1. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/PKG-INFO +17 -13
  2. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/README.md +14 -10
  3. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/__init__.py +47 -8
  4. dazzle_filekit-0.3.0/dazzle_filekit/_fallback.py +158 -0
  5. dazzle_filekit-0.3.0/dazzle_filekit/content.py +74 -0
  6. dazzle_filekit-0.3.0/dazzle_filekit/links.py +318 -0
  7. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/metadata.py +8 -3
  8. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/operations.py +201 -34
  9. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/paths.py +77 -70
  10. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/utils/compat.py +46 -26
  11. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/utils/validation.py +86 -15
  12. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit.egg-info/PKG-INFO +17 -13
  13. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit.egg-info/SOURCES.txt +10 -0
  14. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit.egg-info/requires.txt +2 -3
  15. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/pyproject.toml +13 -2
  16. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/setup.py +1 -1
  17. dazzle_filekit-0.3.0/tests/test_content_and_process.py +90 -0
  18. dazzle_filekit-0.3.0/tests/test_fallback.py +118 -0
  19. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/tests/test_import_stability.py +60 -10
  20. dazzle_filekit-0.3.0/tests/test_link_primitives.py +252 -0
  21. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/tests/test_paths_v024_enrichments.py +13 -5
  22. dazzle_filekit-0.3.0/tests/test_phase_b_absorb_and_v9.py +90 -0
  23. dazzle_filekit-0.3.0/tests/test_phase_c_renames.py +127 -0
  24. dazzle_filekit-0.3.0/tests/test_phase_d_typeddicts.py +75 -0
  25. dazzle_filekit-0.3.0/tests/test_resolver_ops.py +108 -0
  26. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/tests/test_smoke.py +4 -3
  27. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/LICENSE +0 -0
  28. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/platform/__init__.py +0 -0
  29. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/platform/unix.py +0 -0
  30. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/platform/windows.py +0 -0
  31. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/utils/__init__.py +0 -0
  32. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/utils/disk.py +0 -0
  33. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/utils/logger.py +0 -0
  34. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/verification.py +0 -0
  35. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit.egg-info/dependency_links.txt +0 -0
  36. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit.egg-info/top_level.txt +0 -0
  37. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/setup.cfg +0 -0
  38. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/tests/test_ads_and_junction_v024.py +0 -0
  39. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/tests/test_auto_naming.py +0 -0
  40. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/tests/test_compat.py +0 -0
  41. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/tests/test_disk.py +0 -0
  42. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/tests/test_metadata_v024_roundtrip.py +0 -0
  43. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/tests/test_operations_primitives_v024.py +0 -0
  44. {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/tests/test_paths_platform_simulation.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: dazzle-filekit
3
- Version: 0.2.4
3
+ Version: 0.3.0
4
4
  Summary: Cross-platform file operations toolkit with path handling, verification, and metadata preservation
5
5
  Author: Dustin
6
6
  Author-email: Dustin Darcy <6962246+djdarcy@users.noreply.github.com>
@@ -28,9 +28,9 @@ Requires-Python: >=3.6
28
28
  Description-Content-Type: text/markdown
29
29
  License-File: LICENSE
30
30
  Requires-Dist: pathlib; python_version < "3.4"
31
+ Requires-Dist: dazzle-lib>=0.2.0
32
+ Requires-Dist: unctools>=0.2.2
31
33
  Requires-Dist: pywin32>=305; sys_platform == "win32"
32
- Provides-Extra: unctools
33
- Requires-Dist: unctools>=0.1.0; extra == "unctools"
34
34
  Provides-Extra: dev
35
35
  Requires-Dist: pytest>=7.0.0; extra == "dev"
36
36
  Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
@@ -66,7 +66,8 @@ A Python toolkit for reliable file operations across Windows, Linux, and macOS.
66
66
  - **File Verification** - Calculate and verify file hashes (MD5, SHA1, SHA256, SHA512)
67
67
  - **Disk Space Checking** - Pre-flight space verification before operations
68
68
  - **Platform Support** - Windows, Linux, and macOS with platform-specific optimizations
69
- - **UNC Path Detection** - Native `is_unc_path` / `get_path_type` helpers; optional [UNCtools](https://github.com/DazzleLib/UNCtools) peer for UNC ↔ drive-letter translation (see [docs/unctools-integration.md](docs/unctools-integration.md))
69
+ - **UNC Path Detection** - Native `is_unc_path` / `classify_fs_object` helpers; built on [UNCtools](https://github.com/DazzleLib/UNCtools) (a hard dependency as of 0.3.0) for UNC ↔ drive-letter translation and the optional path-variant resolver edge (see [docs/unctools-integration.md](docs/unctools-integration.md))
70
+ - **Link Primitives** - `analyze_link` / `create_junction` / `create_hardlink` / `read_link_target` (intrinsic link analysis; junctions via PowerShell, no `cmd`)
70
71
 
71
72
  ## Why dazzle-filekit?
72
73
 
@@ -87,14 +88,15 @@ dazzle-filekit was designed for applications requiring reliable file operations
87
88
  pip install dazzle-filekit
88
89
  ```
89
90
 
91
+ This pulls in the stack bedrock and path-identity layer automatically:
92
+ `dazzle-lib` (shared Protocols/types) and `unctools` (UNC ↔ drive-letter
93
+ identity). As of 0.3.0 both are **required** -- `unctools` backs the
94
+ fallback-aware file operations (`copy_file(..., try_path_variants=True)`,
95
+ `open_file`, etc.) via the `PathVariantResolver` seam.
96
+
90
97
  ### Optional Dependencies
91
98
 
92
99
  ```bash
93
- # UNCtools peer install (enables UNC ↔ drive-letter translation
94
- # via user-side composition; filekit does not import unctools directly).
95
- # See docs/unctools-integration.md for composition patterns.
96
- pip install 'dazzle-filekit[unctools]'
97
-
98
100
  # Development tools
99
101
  pip install 'dazzle-filekit[dev]'
100
102
  ```
@@ -130,10 +132,11 @@ if path_exists_cross_platform("/c/Users/foo/file.txt"):
130
132
  ### Path Operations
131
133
 
132
134
  ```python
133
- from dazzle_filekit import normalize_path, find_files, is_unc_path
135
+ from dazzle_filekit import normalize_cross_platform_path, find_files, is_unc_path
134
136
 
135
- # Normalize paths (returns Path object)
136
- path = normalize_path("/some/path/../file.txt")
137
+ # Normalize paths (returns Path object). resolve=True follows symlinks;
138
+ # the default resolve=False is link-safe.
139
+ path = normalize_cross_platform_path("/some/path/../file.txt")
137
140
  print(path) # PosixPath('/some/file.txt') or WindowsPath('C:/some/file.txt')
138
141
 
139
142
  # Find files with patterns (returns list of path strings)
@@ -265,7 +268,8 @@ For the full function-by-function reference, see
265
268
  | **Platform (Windows)** | `dazzle_filekit.platform.windows` -- `detect_alternate_streams`, `has_significant_ads`, `is_admin` |
266
269
  | **Disk space** | `get_disk_usage`, `check_disk_space`, `calculate_total_size`, `ensure_disk_space` |
267
270
  | **Verification** | `calculate_file_hash`, `verify_file_hash`, `verify_files_with_manifest`, `compare_directories` |
268
- | **UNC detection** | `is_unc_path`, `get_path_type` (compose with UNCtools for translation -- see [docs/unctools-integration.md](docs/unctools-integration.md)) |
271
+ | **UNC detection** | `is_unc_path`, `classify_fs_object` (UNCtools is the hard-dep L0 layer for translation + the resolver edge -- see [docs/unctools-integration.md](docs/unctools-integration.md)) |
272
+ | **Link primitives** | `analyze_link`, `detect_link_type`, `read_link_target`, `create_junction`, `create_hardlink` |
269
273
 
270
274
  ## Platform Support
271
275
 
@@ -24,7 +24,8 @@ A Python toolkit for reliable file operations across Windows, Linux, and macOS.
24
24
  - **File Verification** - Calculate and verify file hashes (MD5, SHA1, SHA256, SHA512)
25
25
  - **Disk Space Checking** - Pre-flight space verification before operations
26
26
  - **Platform Support** - Windows, Linux, and macOS with platform-specific optimizations
27
- - **UNC Path Detection** - Native `is_unc_path` / `get_path_type` helpers; optional [UNCtools](https://github.com/DazzleLib/UNCtools) peer for UNC ↔ drive-letter translation (see [docs/unctools-integration.md](docs/unctools-integration.md))
27
+ - **UNC Path Detection** - Native `is_unc_path` / `classify_fs_object` helpers; built on [UNCtools](https://github.com/DazzleLib/UNCtools) (a hard dependency as of 0.3.0) for UNC ↔ drive-letter translation and the optional path-variant resolver edge (see [docs/unctools-integration.md](docs/unctools-integration.md))
28
+ - **Link Primitives** - `analyze_link` / `create_junction` / `create_hardlink` / `read_link_target` (intrinsic link analysis; junctions via PowerShell, no `cmd`)
28
29
 
29
30
  ## Why dazzle-filekit?
30
31
 
@@ -45,14 +46,15 @@ dazzle-filekit was designed for applications requiring reliable file operations
45
46
  pip install dazzle-filekit
46
47
  ```
47
48
 
49
+ This pulls in the stack bedrock and path-identity layer automatically:
50
+ `dazzle-lib` (shared Protocols/types) and `unctools` (UNC ↔ drive-letter
51
+ identity). As of 0.3.0 both are **required** -- `unctools` backs the
52
+ fallback-aware file operations (`copy_file(..., try_path_variants=True)`,
53
+ `open_file`, etc.) via the `PathVariantResolver` seam.
54
+
48
55
  ### Optional Dependencies
49
56
 
50
57
  ```bash
51
- # UNCtools peer install (enables UNC ↔ drive-letter translation
52
- # via user-side composition; filekit does not import unctools directly).
53
- # See docs/unctools-integration.md for composition patterns.
54
- pip install 'dazzle-filekit[unctools]'
55
-
56
58
  # Development tools
57
59
  pip install 'dazzle-filekit[dev]'
58
60
  ```
@@ -88,10 +90,11 @@ if path_exists_cross_platform("/c/Users/foo/file.txt"):
88
90
  ### Path Operations
89
91
 
90
92
  ```python
91
- from dazzle_filekit import normalize_path, find_files, is_unc_path
93
+ from dazzle_filekit import normalize_cross_platform_path, find_files, is_unc_path
92
94
 
93
- # Normalize paths (returns Path object)
94
- path = normalize_path("/some/path/../file.txt")
95
+ # Normalize paths (returns Path object). resolve=True follows symlinks;
96
+ # the default resolve=False is link-safe.
97
+ path = normalize_cross_platform_path("/some/path/../file.txt")
95
98
  print(path) # PosixPath('/some/file.txt') or WindowsPath('C:/some/file.txt')
96
99
 
97
100
  # Find files with patterns (returns list of path strings)
@@ -223,7 +226,8 @@ For the full function-by-function reference, see
223
226
  | **Platform (Windows)** | `dazzle_filekit.platform.windows` -- `detect_alternate_streams`, `has_significant_ads`, `is_admin` |
224
227
  | **Disk space** | `get_disk_usage`, `check_disk_space`, `calculate_total_size`, `ensure_disk_space` |
225
228
  | **Verification** | `calculate_file_hash`, `verify_file_hash`, `verify_files_with_manifest`, `compare_directories` |
226
- | **UNC detection** | `is_unc_path`, `get_path_type` (compose with UNCtools for translation -- see [docs/unctools-integration.md](docs/unctools-integration.md)) |
229
+ | **UNC detection** | `is_unc_path`, `classify_fs_object` (UNCtools is the hard-dep L0 layer for translation + the resolver edge -- see [docs/unctools-integration.md](docs/unctools-integration.md)) |
230
+ | **Link primitives** | `analyze_link`, `detect_link_type`, `read_link_target`, `create_junction`, `create_hardlink` |
227
231
 
228
232
  ## Platform Support
229
233
 
@@ -24,25 +24,27 @@ if not logger.handlers:
24
24
 
25
25
  # Import core functionality
26
26
  from .paths import (
27
- normalize_path,
28
- normalize_path_no_resolve,
29
27
  is_same_file,
30
28
  split_drive_letter,
31
29
  is_unc_path,
32
30
  get_relative_path,
31
+ compute_relative_path,
33
32
  create_dest_path,
34
33
  find_files,
35
34
  find_regex_files,
36
35
  collect_files_from_include_file,
37
36
  create_parent_dirs,
38
37
  ensure_unique_path,
39
- get_path_type
38
+ classify_fs_object
40
39
  )
41
40
 
42
41
  from .utils.compat import (
43
42
  normalize_cross_platform_path,
44
43
  resolve_cross_platform_path,
45
44
  path_exists_cross_platform,
45
+ fix_path_case,
46
+ path_exists_case_sensitive,
47
+ get_case_sensitive_path,
46
48
  is_windows,
47
49
  is_unix,
48
50
  is_wsl,
@@ -60,10 +62,12 @@ from .utils.disk import (
60
62
  from .operations import (
61
63
  copy_file,
62
64
  move_file,
65
+ open_file,
63
66
  collect_file_metadata,
64
67
  apply_file_metadata,
65
68
  copy_files_with_path,
66
69
  move_files_with_path,
70
+ process_files,
67
71
  create_directory_structure,
68
72
  remove_file,
69
73
  remove_directory,
@@ -97,7 +101,24 @@ from .metadata import (
97
101
  metadata_to_json,
98
102
  )
99
103
 
100
- __version__ = '0.2.4'
104
+ # v0.3.0 content operations -- the L1 home of unctools' removed
105
+ # replace_in_file / batch_replace_in_files (STACK-MAP D7).
106
+ from . import content # noqa: F401
107
+ from .content import replace_in_file, batch_replace_in_files
108
+
109
+ # v0.3.0 intrinsic link primitives (#15 Phase A) -- the L1 home of
110
+ # preservelib's intrinsic link analysis + junction/hardlink creation.
111
+ from . import links # noqa: F401
112
+ from .links import (
113
+ LinkInfo,
114
+ analyze_link,
115
+ detect_link_type,
116
+ read_link_target,
117
+ create_junction,
118
+ create_hardlink,
119
+ )
120
+
121
+ __version__ = '0.3.0'
101
122
 
102
123
  def configure_logging(level=logging.INFO, log_file=None):
103
124
  """
@@ -164,24 +185,26 @@ __all__ = [
164
185
  'enable_verbose_logging',
165
186
 
166
187
  # Path functions
167
- 'normalize_path',
168
- 'normalize_path_no_resolve',
169
188
  'is_same_file',
170
189
  'split_drive_letter',
171
190
  'is_unc_path',
172
191
  'get_relative_path',
192
+ 'compute_relative_path',
173
193
  'create_dest_path',
174
194
  'find_files',
175
195
  'find_regex_files',
176
196
  'collect_files_from_include_file',
177
197
  'create_parent_dirs',
178
198
  'ensure_unique_path',
179
- 'get_path_type',
199
+ 'classify_fs_object',
180
200
 
181
201
  # Cross-platform path utilities
182
202
  'normalize_cross_platform_path',
183
203
  'resolve_cross_platform_path',
184
204
  'path_exists_cross_platform',
205
+ 'fix_path_case',
206
+ 'path_exists_case_sensitive',
207
+ 'get_case_sensitive_path',
185
208
  'is_windows',
186
209
  'is_unix',
187
210
  'is_wsl',
@@ -197,10 +220,12 @@ __all__ = [
197
220
  # Operation functions
198
221
  'copy_file',
199
222
  'move_file',
223
+ 'open_file',
200
224
  'collect_file_metadata',
201
225
  'apply_file_metadata',
202
226
  'copy_files_with_path',
203
227
  'move_files_with_path',
228
+ 'process_files',
204
229
  'create_directory_structure',
205
230
  'remove_file',
206
231
  'remove_directory',
@@ -217,7 +242,21 @@ __all__ = [
217
242
  'restore_windows_creation_time',
218
243
  'compare_metadata',
219
244
  'metadata_to_json',
220
-
245
+
246
+ # Content operations (v0.3.0)
247
+ 'content',
248
+ 'replace_in_file',
249
+ 'batch_replace_in_files',
250
+
251
+ # Intrinsic link primitives (v0.3.0, #15 Phase A)
252
+ 'links',
253
+ 'LinkInfo',
254
+ 'analyze_link',
255
+ 'detect_link_type',
256
+ 'read_link_target',
257
+ 'create_junction',
258
+ 'create_hardlink',
259
+
221
260
  # Verification functions
222
261
  'calculate_file_hash',
223
262
  'verify_file_hash',
@@ -0,0 +1,158 @@
1
+ """Fallback-aware operation retry across path-name variants.
2
+
3
+ This is the L1 (filekit) side of the STACK-MAP ``path_variant_resolver`` seam
4
+ (decision D7). A filekit file operation can optionally retry under alternative
5
+ names for a path -- e.g. a Windows UNC path (``\\\\server\\share\\f``) and its
6
+ mapped-drive equivalent (``Z:\\f``) name the same file, yet a security zone can
7
+ block opening/copying via one name while the other works, even though both
8
+ *exist*.
9
+
10
+ Who knows what a path's other names are is supplied by a
11
+ :class:`dazzle_lib.PathVariantResolver`. filekit's default resolver is backed by
12
+ unctools (a **hard** dependency, L1->L0): filekit is a cross-platform file-ops
13
+ toolkit and already requires pywin32 on Windows, so an extra small pure-Python
14
+ dependency is cheap and removes the awkwardness of optional discovery. The
15
+ Protocol is retained for what it actually buys: tests inject a fake resolver
16
+ (no real UNC/network needed), and a different identity source can be swapped in
17
+ via the ``resolver=`` parameter. The two layers meet at the resolver contract,
18
+ not in a shared object graph.
19
+
20
+ Design invariants:
21
+
22
+ - The default behaviour of every operation is unchanged: the retry path is only
23
+ taken when a caller explicitly opts in (``try_path_variants=True``).
24
+ - A resolver is always available (unctools is a hard dep), so an opted-in
25
+ fallback is never silently dropped -- it simply always runs.
26
+ - The retry runners re-raise the ORIGINAL error if every variant fails.
27
+ """
28
+
29
+ from __future__ import annotations
30
+
31
+ import logging
32
+ from typing import Callable, List, Optional, TypeVar
33
+
34
+ from dazzle_lib import PathVariantResolver
35
+ from unctools import convert_to_local, convert_to_unc, is_unc_path
36
+
37
+ logger = logging.getLogger(__name__)
38
+
39
+ T = TypeVar("T")
40
+
41
+ # Retry on these. PermissionError (the Windows security-zone case) is the
42
+ # motivating one; FileNotFoundError (a name not currently mounted) is the other.
43
+ # Both are OSError subclasses; listing them documents intent.
44
+ RETRYABLE = (PermissionError, FileNotFoundError, OSError)
45
+
46
+
47
+ class UnctoolsResolver:
48
+ """filekit's default :class:`dazzle_lib.PathVariantResolver`, backed by
49
+ unctools. Proposes a path's UNC<->mapped-drive alternate name using the
50
+ system's live network mappings."""
51
+
52
+ def variants(self, path: str) -> List[str]:
53
+ out = [path]
54
+ try:
55
+ alt = str(convert_to_local(path)) if is_unc_path(path) else str(convert_to_unc(path))
56
+ if alt and alt != path:
57
+ out.append(alt)
58
+ except Exception as e: # a resolver must never raise into the operation
59
+ logger.debug("unctools variant resolution failed for %r: %s", path, e)
60
+ return out
61
+
62
+
63
+ # Module singleton -- stateless, so one instance is fine.
64
+ _DEFAULT_RESOLVER = UnctoolsResolver()
65
+
66
+
67
+ def default_resolver() -> PathVariantResolver:
68
+ """Return filekit's default (unctools-backed) resolver. Always available;
69
+ callers may still inject their own via ``resolver=``."""
70
+ return _DEFAULT_RESOLVER
71
+
72
+
73
+ def variants_of(path: str, resolver: Optional[PathVariantResolver] = None) -> List[str]:
74
+ """Ordered, de-duplicated candidate names for ``path`` (original first)."""
75
+ r = resolver if resolver is not None else _DEFAULT_RESOLVER
76
+ ordered: List[str] = []
77
+ for cand in (path, *r.variants(path)):
78
+ if cand and cand not in ordered:
79
+ ordered.append(cand)
80
+ return ordered
81
+
82
+
83
+ # ---------------------------------------------------------------------------
84
+ # Retry runners. They re-raise the ORIGINAL error if every variant fails.
85
+ # ---------------------------------------------------------------------------
86
+
87
+ def retry_single(op: Callable[[str], T], path: str, *, feature: str = "operation",
88
+ resolver: Optional[PathVariantResolver] = None,
89
+ exc=RETRYABLE) -> T:
90
+ """Run ``op(path)``; on a retryable error, retry under each variant of
91
+ ``path``; re-raise the first error if all attempts fail."""
92
+ first_error: Optional[BaseException] = None
93
+ for cand in variants_of(path, resolver):
94
+ try:
95
+ return op(cand)
96
+ except exc as e:
97
+ if first_error is None:
98
+ first_error = e
99
+ logger.debug("%s failed under %r: %s", feature, cand, e)
100
+ assert first_error is not None # variants_of always yields >= 1 candidate
101
+ raise first_error
102
+
103
+
104
+ def retry_pair(op: Callable[[str, str], T], src: str, dst: str, *, feature: str = "operation",
105
+ resolver: Optional[PathVariantResolver] = None,
106
+ exc=RETRYABLE) -> T:
107
+ """Run ``op(src, dst)``; on a retryable error, retry across the bounded
108
+ cartesian product of src-variants x dst-variants (original pair first);
109
+ re-raise the first error if all combinations fail.
110
+
111
+ Mirrors the legacy ``unctools.safe_copy`` semantic: either endpoint may be
112
+ the blocked name, so both are varied.
113
+ """
114
+ src_cands = variants_of(src, resolver)
115
+ dst_cands = variants_of(dst, resolver)
116
+ pairs = [(src, dst)] + [(s, d) for s in src_cands for d in dst_cands]
117
+ tried = set()
118
+ first_error: Optional[BaseException] = None
119
+ for s, d in pairs:
120
+ if (s, d) in tried:
121
+ continue
122
+ tried.add((s, d))
123
+ try:
124
+ return op(s, d)
125
+ except exc as e:
126
+ if first_error is None:
127
+ first_error = e
128
+ logger.debug("%s failed for %r -> %r: %s", feature, s, d, e)
129
+ assert first_error is not None
130
+ raise first_error
131
+
132
+
133
+ def retry_pair_bool(op_bool: Callable[[str, str], bool], src: str, dst: str, *,
134
+ feature: str = "operation",
135
+ resolver: Optional[PathVariantResolver] = None,
136
+ exc=RETRYABLE) -> bool:
137
+ """Like :func:`retry_pair`, but for a **bool**-returning op (True = success).
138
+
139
+ Tries the original ``(src, dst)`` pair, then the bounded product of
140
+ src-variants x dst-variants, returning True on the first success. A falsy
141
+ return OR a retryable exception means "try the next pair". Returns False if
142
+ every pair fails -- matching the bool contract of ``copy_file``/``move_file``
143
+ (which swallow errors to False rather than raising).
144
+ """
145
+ src_cands = variants_of(src, resolver)
146
+ dst_cands = variants_of(dst, resolver)
147
+ pairs = [(src, dst)] + [(s, d) for s in src_cands for d in dst_cands]
148
+ tried = set()
149
+ for s, d in pairs:
150
+ if (s, d) in tried:
151
+ continue
152
+ tried.add((s, d))
153
+ try:
154
+ if op_bool(s, d):
155
+ return True
156
+ except exc as e:
157
+ logger.debug("%s failed for %r -> %r: %s", feature, s, d, e)
158
+ return False
@@ -0,0 +1,74 @@
1
+ """Text-content file operations.
2
+
3
+ The L1 home of unctools' removed ``replace_in_file`` / ``batch_replace_in_files``
4
+ (STACK-MAP D7: editing a file's *content* is a file operation, so it belongs in
5
+ dazzle-filekit, not the path-identity layer). Built on the fallback-aware
6
+ ``open_file`` (read), ``atomic_write_text`` (crash-safe write -- a strict upgrade
7
+ over the original's plain write), and ``process_files`` (batch).
8
+ """
9
+
10
+ import logging
11
+ from pathlib import Path
12
+ from typing import Dict, Optional, Union
13
+
14
+ from dazzle_lib import PathVariantResolver
15
+
16
+ from .operations import atomic_write_text, open_file, process_files
17
+
18
+ logger = logging.getLogger(__name__)
19
+
20
+
21
+ def replace_in_file(
22
+ file_path: Union[str, Path],
23
+ old_text: str,
24
+ new_text: str,
25
+ *,
26
+ encoding: str = "utf-8",
27
+ try_path_variants: bool = False,
28
+ resolver: Optional[PathVariantResolver] = None,
29
+ ) -> bool:
30
+ """Replace ``old_text`` with ``new_text`` in ``file_path``.
31
+
32
+ Reads via the fallback-aware :func:`open_file` and writes via
33
+ :func:`atomic_write_text` (so a crash mid-write cannot truncate the file).
34
+ Returns True if the file was modified, False if ``old_text`` was not present
35
+ (logged as a warning) or on error.
36
+ """
37
+ try:
38
+ with open_file(file_path, "r", encoding=encoding,
39
+ try_path_variants=try_path_variants, resolver=resolver) as f:
40
+ content = f.read()
41
+
42
+ if old_text not in content:
43
+ logger.warning(f"Text not found in file {file_path}")
44
+ return False
45
+
46
+ atomic_write_text(file_path, content.replace(old_text, new_text), encoding=encoding)
47
+ return True
48
+ except Exception as e:
49
+ logger.error(f"Error replacing text in file {file_path}: {e}")
50
+ return False
51
+
52
+
53
+ def batch_replace_in_files(
54
+ directory: Union[str, Path],
55
+ old_text: str,
56
+ new_text: str,
57
+ pattern: str = "*.txt",
58
+ recursive: bool = True,
59
+ *,
60
+ encoding: str = "utf-8",
61
+ try_path_variants: bool = False,
62
+ resolver: Optional[PathVariantResolver] = None,
63
+ ) -> Dict[str, bool]:
64
+ """Run :func:`replace_in_file` over every file matching ``pattern`` under
65
+ ``directory`` (via :func:`process_files`).
66
+
67
+ Returns ``{str(path): modified?}`` (False for unmatched / errored files).
68
+ """
69
+ def _cb(path: Path) -> bool:
70
+ return replace_in_file(path, old_text, new_text, encoding=encoding,
71
+ try_path_variants=try_path_variants, resolver=resolver)
72
+
73
+ return process_files(directory, _cb, pattern, recursive,
74
+ try_path_variants=try_path_variants, resolver=resolver)