dazzle-filekit 0.3.2__tar.gz → 0.3.3__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.3.2 → dazzle_filekit-0.3.3}/PKG-INFO +1 -1
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/dazzle_filekit/__init__.py +32 -1
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/dazzle_filekit/links.py +11 -1
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/dazzle_filekit/operations.py +143 -1
- dazzle_filekit-0.3.3/dazzle_filekit/pathenv.py +123 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/dazzle_filekit/paths.py +14 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/dazzle_filekit/utils/compat.py +12 -2
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/dazzle_filekit/utils/validation.py +18 -3
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/dazzle_filekit/verification.py +231 -1
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/dazzle_filekit.egg-info/PKG-INFO +1 -1
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/dazzle_filekit.egg-info/SOURCES.txt +7 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/pyproject.toml +1 -1
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/setup.py +1 -1
- dazzle_filekit-0.3.3/tests/test_atomic_stream_writer.py +130 -0
- dazzle_filekit-0.3.3/tests/test_atomic_write_retry.py +30 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/tests/test_import_stability.py +9 -0
- dazzle_filekit-0.3.3/tests/test_junction_detection_improvements.py +147 -0
- dazzle_filekit-0.3.3/tests/test_native_hash_backend.py +183 -0
- dazzle_filekit-0.3.3/tests/test_pathenv.py +152 -0
- dazzle_filekit-0.3.3/tests/test_pathenv_edgecases.py +184 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/LICENSE +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/README.md +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/dazzle_filekit/_fallback.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/dazzle_filekit/content.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/dazzle_filekit/metadata.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/dazzle_filekit/platform/__init__.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/dazzle_filekit/platform/unix.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/dazzle_filekit/platform/windows.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/dazzle_filekit/utils/__init__.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/dazzle_filekit/utils/disk.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/dazzle_filekit/utils/logger.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/dazzle_filekit.egg-info/dependency_links.txt +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/dazzle_filekit.egg-info/requires.txt +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/dazzle_filekit.egg-info/top_level.txt +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/setup.cfg +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/tests/test_ads_and_junction_v024.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/tests/test_auto_naming.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/tests/test_compat.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/tests/test_content_and_process.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/tests/test_disk.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/tests/test_fallback.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/tests/test_link_primitives.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/tests/test_metadata_v024_roundtrip.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/tests/test_operations_primitives_v024.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/tests/test_paths_platform_simulation.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/tests/test_paths_v024_enrichments.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/tests/test_phase_b_absorb_and_v9.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/tests/test_phase_c_renames.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/tests/test_phase_d_typeddicts.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/tests/test_resolver_ops.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/tests/test_smoke.py +0 -0
- {dazzle_filekit-0.3.2 → dazzle_filekit-0.3.3}/tests/test_symlink_timestamps_v031.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: dazzle-filekit
|
|
3
|
-
Version: 0.3.
|
|
3
|
+
Version: 0.3.3
|
|
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>
|
|
@@ -76,10 +76,15 @@ from .operations import (
|
|
|
76
76
|
atomic_write_text,
|
|
77
77
|
atomic_write_json,
|
|
78
78
|
copy_tree_preserving_links,
|
|
79
|
+
# Streaming atomic writer (from dazzlesum's MonolithicWriter)
|
|
80
|
+
AtomicStreamWriter,
|
|
79
81
|
)
|
|
80
82
|
|
|
81
83
|
from .verification import (
|
|
82
84
|
calculate_file_hash,
|
|
85
|
+
# Native checksum-tool backend (from dazzlesum)
|
|
86
|
+
detect_native_hash_tool,
|
|
87
|
+
calculate_file_hash_native,
|
|
83
88
|
verify_file_hash,
|
|
84
89
|
verify_files_with_manifest,
|
|
85
90
|
calculate_directory_hashes,
|
|
@@ -119,7 +124,20 @@ from .links import (
|
|
|
119
124
|
remove_link,
|
|
120
125
|
)
|
|
121
126
|
|
|
122
|
-
|
|
127
|
+
# v0.3.3 declared-platform PATH-value helpers (dazzlecmd#103 homing) --
|
|
128
|
+
# the provenance-typed sibling of the host-directional normalizers.
|
|
129
|
+
from . import pathenv # noqa: F401
|
|
130
|
+
from .pathenv import (
|
|
131
|
+
PLATFORM_WINDOWS,
|
|
132
|
+
PLATFORM_POSIX,
|
|
133
|
+
host_path_platform,
|
|
134
|
+
split_path_value,
|
|
135
|
+
normalize_path_entry,
|
|
136
|
+
path_value_contains,
|
|
137
|
+
append_path_value,
|
|
138
|
+
)
|
|
139
|
+
|
|
140
|
+
__version__ = '0.3.3'
|
|
123
141
|
|
|
124
142
|
def configure_logging(level=logging.INFO, log_file=None):
|
|
125
143
|
"""
|
|
@@ -236,6 +254,7 @@ __all__ = [
|
|
|
236
254
|
'atomic_write_text',
|
|
237
255
|
'atomic_write_json',
|
|
238
256
|
'copy_tree_preserving_links',
|
|
257
|
+
'AtomicStreamWriter',
|
|
239
258
|
|
|
240
259
|
# Rich metadata module (v0.2.4)
|
|
241
260
|
'metadata',
|
|
@@ -259,8 +278,20 @@ __all__ = [
|
|
|
259
278
|
'create_hardlink',
|
|
260
279
|
'remove_link',
|
|
261
280
|
|
|
281
|
+
# Declared-platform PATH-value helpers (v0.3.3)
|
|
282
|
+
'pathenv',
|
|
283
|
+
'PLATFORM_WINDOWS',
|
|
284
|
+
'PLATFORM_POSIX',
|
|
285
|
+
'host_path_platform',
|
|
286
|
+
'split_path_value',
|
|
287
|
+
'normalize_path_entry',
|
|
288
|
+
'path_value_contains',
|
|
289
|
+
'append_path_value',
|
|
290
|
+
|
|
262
291
|
# Verification functions
|
|
263
292
|
'calculate_file_hash',
|
|
293
|
+
'detect_native_hash_tool',
|
|
294
|
+
'calculate_file_hash_native',
|
|
264
295
|
'verify_file_hash',
|
|
265
296
|
'verify_files_with_manifest',
|
|
266
297
|
'calculate_directory_hashes',
|
|
@@ -97,10 +97,20 @@ def detect_link_type(path: Union[str, Path]) -> Optional[str]:
|
|
|
97
97
|
Returns ``'symlink'``, ``'junction'`` (Windows), or ``'hardlink'`` (a file
|
|
98
98
|
whose ``st_nlink > 1``). Hard links are otherwise indistinguishable from
|
|
99
99
|
regular files, so a single-name file is reported as ``None``.
|
|
100
|
+
|
|
101
|
+
Existence is checked with ``os.lstat`` (the link ITSELF), not
|
|
102
|
+
``Path.exists()`` (which follows the link): a junction whose target is
|
|
103
|
+
missing is still a junction and must be reported as one, so
|
|
104
|
+
``analyze_link`` can mark it broken. The previous ``exists()`` gate
|
|
105
|
+
special-cased broken symlinks but silently dropped broken junctions
|
|
106
|
+
(contributed from dazzlesum, whose walker must refuse to traverse
|
|
107
|
+
broken junctions rather than treat them as plain directories).
|
|
100
108
|
"""
|
|
101
109
|
p = Path(path)
|
|
102
110
|
|
|
103
|
-
|
|
111
|
+
try:
|
|
112
|
+
os.lstat(p)
|
|
113
|
+
except OSError:
|
|
104
114
|
return None
|
|
105
115
|
|
|
106
116
|
if p.is_symlink():
|
|
@@ -66,7 +66,20 @@ def atomic_write_text(
|
|
|
66
66
|
tmp_path = path.with_suffix(path.suffix + ".tmp")
|
|
67
67
|
with open(tmp_path, "w", encoding=encoding, newline=newline) as f:
|
|
68
68
|
f.write(content)
|
|
69
|
-
|
|
69
|
+
# Windows: antivirus/indexers briefly lock freshly-written files, so a
|
|
70
|
+
# first os.replace can fail with PermissionError [WinError 5] even
|
|
71
|
+
# though nothing of ours holds the file (observed in the wild: one
|
|
72
|
+
# random victim test per dazzlecmd full-suite run). A short bounded
|
|
73
|
+
# retry absorbs the transient; a REAL permission problem still
|
|
74
|
+
# surfaces after ~0.3s total.
|
|
75
|
+
for attempt in range(6):
|
|
76
|
+
try:
|
|
77
|
+
os.replace(str(tmp_path), str(path))
|
|
78
|
+
break
|
|
79
|
+
except PermissionError:
|
|
80
|
+
if attempt == 5:
|
|
81
|
+
raise
|
|
82
|
+
time.sleep(0.01 * (2 ** attempt)) # 10..160ms backoff
|
|
70
83
|
|
|
71
84
|
|
|
72
85
|
def atomic_write_json(
|
|
@@ -107,6 +120,135 @@ def atomic_write_json(
|
|
|
107
120
|
atomic_write_text(path, text, encoding="utf-8")
|
|
108
121
|
|
|
109
122
|
|
|
123
|
+
class AtomicStreamWriter:
|
|
124
|
+
"""Streaming counterpart of :func:`atomic_write_text`.
|
|
125
|
+
|
|
126
|
+
For content too large -- or too incremental -- to build in memory:
|
|
127
|
+
writes go to a sibling ``.tmp`` file, and on successful close the tmp
|
|
128
|
+
is renamed over ``path`` via ``os.replace``. Readers observing ``path``
|
|
129
|
+
see either the old contents or the complete new contents, never a
|
|
130
|
+
partial write. On failure (an exception inside the ``with`` block, or
|
|
131
|
+
an explicit ``close(success=False)``) the destination is untouched and
|
|
132
|
+
the tmp is removed.
|
|
133
|
+
|
|
134
|
+
Options (all keyword-only):
|
|
135
|
+
|
|
136
|
+
* ``resume_from_existing``: seed the tmp with the current contents of
|
|
137
|
+
``path`` (``shutil.copy2``) and open it in append mode -- for
|
|
138
|
+
resuming an interrupted long-running write. When ``path`` does not
|
|
139
|
+
exist this degrades to a normal fresh write.
|
|
140
|
+
* ``fsync_on_flush``: make each :meth:`flush` also ``os.fsync``,
|
|
141
|
+
bounding data loss to the last flush for observers tailing the tmp
|
|
142
|
+
during very long runs (fsync failures are swallowed -- not every
|
|
143
|
+
platform/filesystem supports it).
|
|
144
|
+
* ``encoding`` / ``newline`` / ``buffering``: passed to ``open()``,
|
|
145
|
+
with the same defaults as :func:`atomic_write_text`.
|
|
146
|
+
|
|
147
|
+
Usage::
|
|
148
|
+
|
|
149
|
+
with AtomicStreamWriter(dest, fsync_on_flush=True) as w:
|
|
150
|
+
for chunk in produce():
|
|
151
|
+
w.write(chunk)
|
|
152
|
+
w.flush()
|
|
153
|
+
|
|
154
|
+
Provenance: generalized from dazzlesum's ``MonolithicWriter`` (its
|
|
155
|
+
streaming checksum-manifest writer), minus the domain concerns
|
|
156
|
+
(headers, footers, overwrite prompts). The one-shot sibling of this
|
|
157
|
+
class is :func:`atomic_write_text`.
|
|
158
|
+
"""
|
|
159
|
+
|
|
160
|
+
def __init__(
|
|
161
|
+
self,
|
|
162
|
+
path: Union[str, Path],
|
|
163
|
+
*,
|
|
164
|
+
encoding: str = "utf-8",
|
|
165
|
+
newline: Optional[str] = None,
|
|
166
|
+
resume_from_existing: bool = False,
|
|
167
|
+
fsync_on_flush: bool = False,
|
|
168
|
+
buffering: int = -1,
|
|
169
|
+
) -> None:
|
|
170
|
+
self.path = Path(path)
|
|
171
|
+
self.tmp_path = self.path.with_suffix(self.path.suffix + ".tmp")
|
|
172
|
+
self.encoding = encoding
|
|
173
|
+
self.newline = newline
|
|
174
|
+
self.resume_from_existing = resume_from_existing
|
|
175
|
+
self.fsync_on_flush = fsync_on_flush
|
|
176
|
+
self.buffering = buffering
|
|
177
|
+
self._file = None
|
|
178
|
+
self._closed = False
|
|
179
|
+
|
|
180
|
+
def __enter__(self) -> "AtomicStreamWriter":
|
|
181
|
+
self.open()
|
|
182
|
+
return self
|
|
183
|
+
|
|
184
|
+
def __exit__(self, exc_type, exc_val, exc_tb) -> None:
|
|
185
|
+
self.close(success=exc_type is None)
|
|
186
|
+
|
|
187
|
+
def open(self) -> "AtomicStreamWriter":
|
|
188
|
+
"""Open the tmp file for writing (called automatically by ``with``)."""
|
|
189
|
+
if self._file is not None:
|
|
190
|
+
return self
|
|
191
|
+
self.path.parent.mkdir(parents=True, exist_ok=True)
|
|
192
|
+
if self.resume_from_existing and self.path.exists():
|
|
193
|
+
shutil.copy2(str(self.path), str(self.tmp_path))
|
|
194
|
+
mode = "a"
|
|
195
|
+
else:
|
|
196
|
+
mode = "w"
|
|
197
|
+
self._file = open(
|
|
198
|
+
self.tmp_path, mode,
|
|
199
|
+
encoding=self.encoding, newline=self.newline,
|
|
200
|
+
buffering=self.buffering,
|
|
201
|
+
)
|
|
202
|
+
self._closed = False
|
|
203
|
+
return self
|
|
204
|
+
|
|
205
|
+
def write(self, text: str) -> None:
|
|
206
|
+
"""Write ``text`` to the tmp file."""
|
|
207
|
+
if self._file is None:
|
|
208
|
+
raise ValueError("AtomicStreamWriter is not open")
|
|
209
|
+
self._file.write(text)
|
|
210
|
+
|
|
211
|
+
def flush(self) -> None:
|
|
212
|
+
"""Flush buffered writes to the tmp file (and fsync when enabled)."""
|
|
213
|
+
if self._file is None:
|
|
214
|
+
raise ValueError("AtomicStreamWriter is not open")
|
|
215
|
+
self._file.flush()
|
|
216
|
+
if self.fsync_on_flush:
|
|
217
|
+
try:
|
|
218
|
+
os.fsync(self._file.fileno())
|
|
219
|
+
except (OSError, AttributeError):
|
|
220
|
+
# fsync is not available on every platform/filesystem
|
|
221
|
+
pass
|
|
222
|
+
|
|
223
|
+
def close(self, success: bool = True) -> None:
|
|
224
|
+
"""Finalize: rename tmp over ``path`` on success, discard it otherwise.
|
|
225
|
+
|
|
226
|
+
Idempotent; safe to call after the ``with`` block has already
|
|
227
|
+
closed the writer.
|
|
228
|
+
"""
|
|
229
|
+
if self._closed:
|
|
230
|
+
return
|
|
231
|
+
self._closed = True
|
|
232
|
+
try:
|
|
233
|
+
if self._file is not None:
|
|
234
|
+
self._file.close()
|
|
235
|
+
self._file = None
|
|
236
|
+
if success:
|
|
237
|
+
os.replace(str(self.tmp_path), str(self.path))
|
|
238
|
+
else:
|
|
239
|
+
self._discard_tmp()
|
|
240
|
+
except Exception:
|
|
241
|
+
self._discard_tmp()
|
|
242
|
+
raise
|
|
243
|
+
|
|
244
|
+
def _discard_tmp(self) -> None:
|
|
245
|
+
try:
|
|
246
|
+
if self.tmp_path.exists():
|
|
247
|
+
os.remove(str(self.tmp_path))
|
|
248
|
+
except OSError as e:
|
|
249
|
+
logger.warning(f"Could not remove temp file {self.tmp_path}: {e}")
|
|
250
|
+
|
|
251
|
+
|
|
110
252
|
# ---------------------------------------------------------------------------
|
|
111
253
|
# Link-safe tree copy (v0.2.4)
|
|
112
254
|
# ---------------------------------------------------------------------------
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
"""PATH-environment-value helpers -- declared-platform parsing and compare.
|
|
2
|
+
|
|
3
|
+
A PATH *value* is a string whose platform semantics are fixed by its
|
|
4
|
+
PROVENANCE, not by the host parsing it: a Windows registry ``Path``
|
|
5
|
+
value stays ``;``-separated, ``%VAR%``-bearing, and case-insensitive
|
|
6
|
+
even when a POSIX CI runner is the one reading it, and a POSIX ``PATH``
|
|
7
|
+
stays ``:``-separated everywhere. That is the opposite philosophy from
|
|
8
|
+
:func:`dazzle_filekit.paths.normalize_cross_platform_path`, which is
|
|
9
|
+
deliberately HOST-directional (it converts filesystem paths toward the
|
|
10
|
+
running OS's native form). Both philosophies are correct -- for their
|
|
11
|
+
own domain. This module is the declared-platform domain's home.
|
|
12
|
+
|
|
13
|
+
Origin: extracted from the dazzlecmd self-setup work (dazzlecmd#103),
|
|
14
|
+
where PATH membership had to be decided against Windows registry values
|
|
15
|
+
with normalized comparison (quotes, trailing slashes, ``%VAR%``
|
|
16
|
+
expansion, casefold) on any host. See the dazzlecmd stack-survey (C6)
|
|
17
|
+
for the layering rationale.
|
|
18
|
+
|
|
19
|
+
``platform`` arguments accept :data:`PLATFORM_WINDOWS`,
|
|
20
|
+
:data:`PLATFORM_POSIX`, or ``None`` meaning the running host. The
|
|
21
|
+
functions are pure string logic -- no filesystem I/O, no registry
|
|
22
|
+
access; persistence stays with callers.
|
|
23
|
+
"""
|
|
24
|
+
|
|
25
|
+
from __future__ import annotations
|
|
26
|
+
|
|
27
|
+
import ntpath
|
|
28
|
+
import os
|
|
29
|
+
from typing import List, Optional
|
|
30
|
+
|
|
31
|
+
PLATFORM_WINDOWS = "windows"
|
|
32
|
+
PLATFORM_POSIX = "posix"
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def host_path_platform() -> str:
|
|
36
|
+
"""The running host's PATH dialect: ``"windows"`` or ``"posix"``."""
|
|
37
|
+
return PLATFORM_WINDOWS if os.name == "nt" else PLATFORM_POSIX
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def _resolve_platform(platform: Optional[str]) -> str:
|
|
41
|
+
if platform is None:
|
|
42
|
+
return host_path_platform()
|
|
43
|
+
if platform not in (PLATFORM_WINDOWS, PLATFORM_POSIX):
|
|
44
|
+
raise ValueError(
|
|
45
|
+
f"platform must be {PLATFORM_WINDOWS!r}, {PLATFORM_POSIX!r}, "
|
|
46
|
+
f"or None (host); got {platform!r}"
|
|
47
|
+
)
|
|
48
|
+
return platform
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def split_path_value(value: str,
|
|
52
|
+
platform: Optional[str] = None) -> List[str]:
|
|
53
|
+
"""Split a PATH value into its non-empty entries.
|
|
54
|
+
|
|
55
|
+
The separator follows the DECLARED platform (``;`` for windows,
|
|
56
|
+
``:`` for posix), never the host's ``os.pathsep`` -- a Windows
|
|
57
|
+
registry value parsed on a POSIX runner still splits on ``;``.
|
|
58
|
+
"""
|
|
59
|
+
sep = ";" if _resolve_platform(platform) == PLATFORM_WINDOWS else ":"
|
|
60
|
+
return [p for p in value.split(sep) if p.strip()]
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def normalize_path_entry(entry: str,
|
|
64
|
+
platform: Optional[str] = None) -> str:
|
|
65
|
+
"""Normalize ONE PATH entry for identity comparison.
|
|
66
|
+
|
|
67
|
+
Windows dialect: strips whitespace and surrounding double quotes
|
|
68
|
+
(quoted entries are legal in Windows PATH values), expands ``%VAR%``
|
|
69
|
+
references the way the OS does for ``REG_EXPAND_SZ`` (via
|
|
70
|
+
:mod:`ntpath` explicitly, so behavior is identical on any host),
|
|
71
|
+
canonicalizes separators to ``\\``, drops trailing separators, and
|
|
72
|
+
casefolds (Windows PATH lookup is case-insensitive). Note an
|
|
73
|
+
inherited stdlib behavior, pinned by test: ``ntpath.expandvars``
|
|
74
|
+
ALSO expands POSIX-spelled ``$VAR`` / ``${VAR}`` references, so
|
|
75
|
+
those expand under this dialect too. Undefined references of either
|
|
76
|
+
spelling stay literal.
|
|
77
|
+
|
|
78
|
+
POSIX dialect: strips whitespace and quotes, canonicalizes
|
|
79
|
+
separators to ``/``, drops trailing slashes; case is preserved.
|
|
80
|
+
|
|
81
|
+
Output is deterministic for a given (entry, platform) pair
|
|
82
|
+
regardless of the host running this code.
|
|
83
|
+
"""
|
|
84
|
+
plat = _resolve_platform(platform)
|
|
85
|
+
e = entry.strip().strip('"')
|
|
86
|
+
if plat == PLATFORM_WINDOWS:
|
|
87
|
+
e = ntpath.expandvars(e)
|
|
88
|
+
e = e.replace("/", "\\")
|
|
89
|
+
e = e.rstrip("\\")
|
|
90
|
+
return e.casefold()
|
|
91
|
+
e = e.replace("\\", "/")
|
|
92
|
+
return e.rstrip("/")
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def path_value_contains(value: str, directory: str,
|
|
96
|
+
platform: Optional[str] = None) -> bool:
|
|
97
|
+
"""True if ``directory`` is among ``value``'s entries.
|
|
98
|
+
|
|
99
|
+
Membership by normalized identity: quotes and trailing separators
|
|
100
|
+
ignored, ``%VAR%`` entries expanded, case-insensitive under the
|
|
101
|
+
windows dialect.
|
|
102
|
+
"""
|
|
103
|
+
target = normalize_path_entry(directory, platform=platform)
|
|
104
|
+
return any(
|
|
105
|
+
normalize_path_entry(p, platform=platform) == target
|
|
106
|
+
for p in split_path_value(value, platform=platform)
|
|
107
|
+
)
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
def append_path_value(value: str, directory: str,
|
|
111
|
+
platform: Optional[str] = None) -> str:
|
|
112
|
+
"""Return ``value`` with ``directory`` appended, if not already present.
|
|
113
|
+
|
|
114
|
+
Pure string construction: no-op (returns ``value`` unchanged) when
|
|
115
|
+
the directory is already a member under normalized identity; an
|
|
116
|
+
empty ``value`` yields ``directory`` alone. The caller persists the
|
|
117
|
+
result wherever it belongs (registry, rc file, environment) -- this
|
|
118
|
+
module never does I/O.
|
|
119
|
+
"""
|
|
120
|
+
if path_value_contains(value, directory, platform=platform):
|
|
121
|
+
return value
|
|
122
|
+
sep = ";" if _resolve_platform(platform) == PLATFORM_WINDOWS else ":"
|
|
123
|
+
return (value.rstrip(sep) + sep + directory) if value else directory
|
|
@@ -3,6 +3,14 @@ Path handling and normalization utilities.
|
|
|
3
3
|
|
|
4
4
|
This module provides functions for path manipulation, normalization, and transformation
|
|
5
5
|
across different platforms, focusing on preserving path information when copying files.
|
|
6
|
+
|
|
7
|
+
Philosophy note: the normalizers here are HOST-directional -- they
|
|
8
|
+
convert portable path formats toward the RUNNING OS's native form
|
|
9
|
+
(``/mnt/c/...`` becomes ``C:\\...`` on Windows and vice versa). For
|
|
10
|
+
strings whose platform semantics are fixed by PROVENANCE instead -- a
|
|
11
|
+
PATH environment value from a Windows registry key stays
|
|
12
|
+
``;``-separated and case-insensitive no matter which host parses it --
|
|
13
|
+
use the declared-platform helpers in :mod:`dazzle_filekit.pathenv`.
|
|
6
14
|
"""
|
|
7
15
|
|
|
8
16
|
import os
|
|
@@ -23,6 +31,12 @@ _MSYS_DRIVE_RE = re.compile(r"^/([a-zA-Z])(/.*)?$")
|
|
|
23
31
|
_WSL_MNT_RE = re.compile(r"^/mnt/([a-zA-Z])(/.*)?$")
|
|
24
32
|
# Windows drive-letter pattern: C:\..., C:/..., c:..., etc.
|
|
25
33
|
_WIN_DRIVE_RE = re.compile(r"^([a-zA-Z]):[\\/](.*)$")
|
|
34
|
+
# MSYS-mangled WSL pattern: Git Bash rewrites /mnt/c/... to
|
|
35
|
+
# <git-root>\mnt\c\... -- match the embedded mnt segment anywhere.
|
|
36
|
+
# Single-sourced here (v0.3.3) so utils/compat.py's existence-probing
|
|
37
|
+
# resolver and this module share ONE spelling; previously compat.py
|
|
38
|
+
# carried an inline byte-identical copy (dazzlecmd stack-survey B1).
|
|
39
|
+
_MANGLED_MNT_RE = re.compile(r"[/\\]mnt[/\\]([a-zA-Z])[/\\](.*)")
|
|
26
40
|
|
|
27
41
|
|
|
28
42
|
def _prepare_path_format(path_str: str) -> str:
|
|
@@ -307,7 +307,10 @@ def resolve_cross_platform_path(path: Union[str, Path]) -> Path:
|
|
|
307
307
|
|
|
308
308
|
if is_windows():
|
|
309
309
|
# Try WSL /mnt/c/ -> C:\ (in case normalization didn't catch it)
|
|
310
|
-
|
|
310
|
+
# Single-sourced pattern (v0.3.3, stack-survey B1): shared with
|
|
311
|
+
# paths._prepare_path_format instead of an inline duplicate.
|
|
312
|
+
from ..paths import _WSL_MNT_RE
|
|
313
|
+
wsl_match = _WSL_MNT_RE.match(str(path))
|
|
311
314
|
if wsl_match:
|
|
312
315
|
drive = wsl_match.group(1).upper()
|
|
313
316
|
rest = (wsl_match.group(2) or '').replace('/', '\\')
|
|
@@ -317,7 +320,10 @@ def resolve_cross_platform_path(path: Union[str, Path]) -> Path:
|
|
|
317
320
|
|
|
318
321
|
# Check for MSYS-mangled WSL paths
|
|
319
322
|
# Git Bash converts /mnt/c/... to C:\Program Files\Git\mnt\c\...
|
|
320
|
-
|
|
323
|
+
# Single-sourced (v0.3.3): this exact pattern previously existed
|
|
324
|
+
# inline here AND in dazzlecmd's fixpath tool, byte-identical.
|
|
325
|
+
from ..paths import _MANGLED_MNT_RE
|
|
326
|
+
mangled = _MANGLED_MNT_RE.search(path_str)
|
|
321
327
|
if mangled:
|
|
322
328
|
drive = mangled.group(1).upper()
|
|
323
329
|
rest = mangled.group(2).replace('/', '\\')
|
|
@@ -327,6 +333,10 @@ def resolve_cross_platform_path(path: Union[str, Path]) -> Path:
|
|
|
327
333
|
|
|
328
334
|
else:
|
|
329
335
|
# On Linux/macOS: try Windows path -> WSL or MSYS format
|
|
336
|
+
# Deliberately NOT swapped for paths._WIN_DRIVE_RE: that pattern
|
|
337
|
+
# anchors with a trailing `$`, this one does not -- equivalent for
|
|
338
|
+
# normal paths but not for pathological embedded-newline input.
|
|
339
|
+
# Additive-only release: behavior preserved bit-for-bit.
|
|
330
340
|
win_match = re.match(r'^([a-zA-Z]):[/\\](.*)', path_str)
|
|
331
341
|
if win_match:
|
|
332
342
|
drive = win_match.group(1).lower()
|
|
@@ -269,9 +269,12 @@ def is_junction(path: Union[str, Path]) -> bool:
|
|
|
269
269
|
(``IO_REPARSE_TAG_MOUNT_POINT`` vs ``IO_REPARSE_TAG_SYMLINK``) and
|
|
270
270
|
different cross-platform semantics.
|
|
271
271
|
|
|
272
|
-
Implementation
|
|
273
|
-
|
|
274
|
-
|
|
272
|
+
Implementation: on Python 3.12+ this is ``os.path.isjunction`` (the
|
|
273
|
+
same mount-point reparse-tag check, answered from a single lstat --
|
|
274
|
+
no handle open). On older Pythons it uses
|
|
275
|
+
``DeviceIoControl(FSCTL_GET_REPARSE_POINT)`` to read the reparse tag
|
|
276
|
+
and check it's specifically ``IO_REPARSE_TAG_MOUNT_POINT``. Both
|
|
277
|
+
methods are reliable; the ctypes path is the only option before 3.12.
|
|
275
278
|
|
|
276
279
|
History: in filekit <= v0.2.3, this function referenced
|
|
277
280
|
``win32file.FILE_ATTRIBUTE_REPARSE_POINT`` (which doesn't exist --
|
|
@@ -294,6 +297,18 @@ def is_junction(path: Union[str, Path]) -> bool:
|
|
|
294
297
|
if not IS_WINDOWS:
|
|
295
298
|
return False
|
|
296
299
|
|
|
300
|
+
# Python 3.12+ fast path: os.path.isjunction performs the same
|
|
301
|
+
# mount-point reparse-tag check from a single lstat -- no handle open,
|
|
302
|
+
# no DeviceIoControl. Matters when callers probe every directory of a
|
|
303
|
+
# large walk (contributed from dazzlesum's traversal profiling: the
|
|
304
|
+
# handle-open probe is ~3 syscalls per directory vs lstat's one).
|
|
305
|
+
isjunction = getattr(os.path, 'isjunction', None)
|
|
306
|
+
if isjunction is not None:
|
|
307
|
+
try:
|
|
308
|
+
return bool(isjunction(str(path)))
|
|
309
|
+
except (OSError, ValueError):
|
|
310
|
+
return False
|
|
311
|
+
|
|
297
312
|
try:
|
|
298
313
|
import ctypes
|
|
299
314
|
from ctypes import wintypes
|