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.
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/PKG-INFO +17 -13
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/README.md +14 -10
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/__init__.py +47 -8
- dazzle_filekit-0.3.0/dazzle_filekit/_fallback.py +158 -0
- dazzle_filekit-0.3.0/dazzle_filekit/content.py +74 -0
- dazzle_filekit-0.3.0/dazzle_filekit/links.py +318 -0
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/metadata.py +8 -3
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/operations.py +201 -34
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/paths.py +77 -70
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/utils/compat.py +46 -26
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/utils/validation.py +86 -15
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit.egg-info/PKG-INFO +17 -13
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit.egg-info/SOURCES.txt +10 -0
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit.egg-info/requires.txt +2 -3
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/pyproject.toml +13 -2
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/setup.py +1 -1
- dazzle_filekit-0.3.0/tests/test_content_and_process.py +90 -0
- dazzle_filekit-0.3.0/tests/test_fallback.py +118 -0
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/tests/test_import_stability.py +60 -10
- dazzle_filekit-0.3.0/tests/test_link_primitives.py +252 -0
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/tests/test_paths_v024_enrichments.py +13 -5
- dazzle_filekit-0.3.0/tests/test_phase_b_absorb_and_v9.py +90 -0
- dazzle_filekit-0.3.0/tests/test_phase_c_renames.py +127 -0
- dazzle_filekit-0.3.0/tests/test_phase_d_typeddicts.py +75 -0
- dazzle_filekit-0.3.0/tests/test_resolver_ops.py +108 -0
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/tests/test_smoke.py +4 -3
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/LICENSE +0 -0
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/platform/__init__.py +0 -0
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/platform/unix.py +0 -0
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/platform/windows.py +0 -0
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/utils/__init__.py +0 -0
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/utils/disk.py +0 -0
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/utils/logger.py +0 -0
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit/verification.py +0 -0
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit.egg-info/dependency_links.txt +0 -0
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/dazzle_filekit.egg-info/top_level.txt +0 -0
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/setup.cfg +0 -0
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/tests/test_ads_and_junction_v024.py +0 -0
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/tests/test_auto_naming.py +0 -0
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/tests/test_compat.py +0 -0
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/tests/test_disk.py +0 -0
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/tests/test_metadata_v024_roundtrip.py +0 -0
- {dazzle_filekit-0.2.4 → dazzle_filekit-0.3.0}/tests/test_operations_primitives_v024.py +0 -0
- {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.
|
|
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` / `
|
|
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
|
|
135
|
+
from dazzle_filekit import normalize_cross_platform_path, find_files, is_unc_path
|
|
134
136
|
|
|
135
|
-
# Normalize paths (returns Path object)
|
|
136
|
-
|
|
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`, `
|
|
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` / `
|
|
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
|
|
93
|
+
from dazzle_filekit import normalize_cross_platform_path, find_files, is_unc_path
|
|
92
94
|
|
|
93
|
-
# Normalize paths (returns Path object)
|
|
94
|
-
|
|
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`, `
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
'
|
|
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)
|