dazzle-filekit 0.3.4__tar.gz → 0.4.1__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.4 → dazzle_filekit-0.4.1}/PKG-INFO +4 -2
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/README.md +3 -1
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/__init__.py +41 -2
- dazzle_filekit-0.4.1/dazzle_filekit/longpath.py +526 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit.egg-info/PKG-INFO +4 -2
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit.egg-info/SOURCES.txt +4 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/pyproject.toml +1 -1
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/setup.py +1 -1
- dazzle_filekit-0.4.1/tests/test_longpath.py +314 -0
- dazzle_filekit-0.4.1/tests/test_longpath_adversarial.py +759 -0
- dazzle_filekit-0.4.1/tests/test_longpath_delta2.py +775 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/LICENSE +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/_fallback.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/content.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/links.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/metadata.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/operations.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/pathenv.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/paths.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/platform/__init__.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/platform/unix.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/platform/windows.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/utils/__init__.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/utils/compat.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/utils/disk.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/utils/logger.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/utils/validation.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/verification.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit.egg-info/dependency_links.txt +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit.egg-info/requires.txt +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit.egg-info/top_level.txt +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/setup.cfg +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_ads_and_junction_v024.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_atomic_stream_writer.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_atomic_write_retry.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_auto_naming.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_compat.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_content_and_process.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_disk.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_fallback.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_import_stability.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_junction_detection_improvements.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_link_fidelity_v034.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_link_primitives.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_metadata_v024_roundtrip.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_native_hash_backend.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_operations_primitives_v024.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_pathenv.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_pathenv_edgecases.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_paths_platform_simulation.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_paths_v024_enrichments.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_phase_b_absorb_and_v9.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_phase_c_renames.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_phase_d_typeddicts.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_resolver_ops.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_smoke.py +0 -0
- {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/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
|
+
Version: 0.4.1
|
|
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>
|
|
@@ -44,7 +44,7 @@ Dynamic: requires-python
|
|
|
44
44
|
|
|
45
45
|
[](https://github.com/DazzleLib/dazzle-filekit/releases)
|
|
46
46
|
[](https://pypi.org/project/dazzle-filekit/)
|
|
47
|
-
[](https://
|
|
47
|
+
[](https://pypistats.org/packages/dazzle-filekit)
|
|
48
48
|
[](https://www.python.org/downloads/)
|
|
49
49
|
[](https://opensource.org/licenses/MIT)
|
|
50
50
|
[](https://github.com/DazzleLib/dazzle-filekit/discussions)
|
|
@@ -68,6 +68,7 @@ A Python toolkit for reliable file operations across Windows, Linux, and macOS.
|
|
|
68
68
|
- **Platform Support** - Windows, Linux, and macOS with platform-specific optimizations
|
|
69
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
70
|
- **Link Primitives** - `analyze_link` / `create_junction` / `create_hardlink` / `read_link_target` (intrinsic link analysis; junctions via PowerShell, no `cmd`)
|
|
71
|
+
- **Long-Path Shims** - `shim_path` makes a file over Windows' 260-character `MAX_PATH` openable by *any* application, by siting a junction at a short root and handing back a shorter name for the same bytes. `\\?\` only lifts the limit at the API layer; it does not help an app that copies the path into a fixed 260-byte buffer (observed in two PDF readers), and nothing outside such an app can fix its buffer. A no-op on Linux/macOS, where `PATH_MAX` is 4096/1024
|
|
71
72
|
|
|
72
73
|
## Why dazzle-filekit?
|
|
73
74
|
|
|
@@ -270,6 +271,7 @@ For the full function-by-function reference, see
|
|
|
270
271
|
| **Verification** | `calculate_file_hash`, `verify_file_hash`, `verify_files_with_manifest`, `compare_directories` |
|
|
271
272
|
| **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
273
|
| **Link primitives** | `analyze_link`, `detect_link_type`, `read_link_target`, `create_junction`, `create_hardlink` |
|
|
274
|
+
| **Long paths** | `dazzle_filekit.longpath` -- `shim_path` (one-call), `needs_shim`, `plan_shim`, `resolve_shim_root`, `budget_for`, `create_shim`, `remove_shim`, `reap_shims` |
|
|
273
275
|
|
|
274
276
|
## Platform Support
|
|
275
277
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://github.com/DazzleLib/dazzle-filekit/releases)
|
|
4
4
|
[](https://pypi.org/project/dazzle-filekit/)
|
|
5
|
-
[](https://
|
|
5
|
+
[](https://pypistats.org/packages/dazzle-filekit)
|
|
6
6
|
[](https://www.python.org/downloads/)
|
|
7
7
|
[](https://opensource.org/licenses/MIT)
|
|
8
8
|
[](https://github.com/DazzleLib/dazzle-filekit/discussions)
|
|
@@ -26,6 +26,7 @@ A Python toolkit for reliable file operations across Windows, Linux, and macOS.
|
|
|
26
26
|
- **Platform Support** - Windows, Linux, and macOS with platform-specific optimizations
|
|
27
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
28
|
- **Link Primitives** - `analyze_link` / `create_junction` / `create_hardlink` / `read_link_target` (intrinsic link analysis; junctions via PowerShell, no `cmd`)
|
|
29
|
+
- **Long-Path Shims** - `shim_path` makes a file over Windows' 260-character `MAX_PATH` openable by *any* application, by siting a junction at a short root and handing back a shorter name for the same bytes. `\\?\` only lifts the limit at the API layer; it does not help an app that copies the path into a fixed 260-byte buffer (observed in two PDF readers), and nothing outside such an app can fix its buffer. A no-op on Linux/macOS, where `PATH_MAX` is 4096/1024
|
|
29
30
|
|
|
30
31
|
## Why dazzle-filekit?
|
|
31
32
|
|
|
@@ -228,6 +229,7 @@ For the full function-by-function reference, see
|
|
|
228
229
|
| **Verification** | `calculate_file_hash`, `verify_file_hash`, `verify_files_with_manifest`, `compare_directories` |
|
|
229
230
|
| **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
231
|
| **Link primitives** | `analyze_link`, `detect_link_type`, `read_link_target`, `create_junction`, `create_hardlink` |
|
|
232
|
+
| **Long paths** | `dazzle_filekit.longpath` -- `shim_path` (one-call), `needs_shim`, `plan_shim`, `resolve_shim_root`, `budget_for`, `create_shim`, `remove_shim`, `reap_shims` |
|
|
231
233
|
|
|
232
234
|
## Platform Support
|
|
233
235
|
|
|
@@ -138,7 +138,29 @@ from .pathenv import (
|
|
|
138
138
|
append_path_value,
|
|
139
139
|
)
|
|
140
140
|
|
|
141
|
-
|
|
141
|
+
# v0.4.0 long-path shims -- the remedy for the condition
|
|
142
|
+
# utils.validation.is_valid_path already detects (paths over MAX_PATH without a
|
|
143
|
+
# \\?\ prefix). Windows-only in effect; a no-op elsewhere.
|
|
144
|
+
from . import longpath # noqa: F401
|
|
145
|
+
from .longpath import (
|
|
146
|
+
MAX_PATH,
|
|
147
|
+
USABLE_PATH,
|
|
148
|
+
DEFAULT_THRESHOLD,
|
|
149
|
+
NAME_MAX,
|
|
150
|
+
SHIM_DIR_NAME,
|
|
151
|
+
ShimPlan,
|
|
152
|
+
needs_shim,
|
|
153
|
+
candidate_roots,
|
|
154
|
+
resolve_shim_root,
|
|
155
|
+
budget_for,
|
|
156
|
+
plan_shim,
|
|
157
|
+
create_shim,
|
|
158
|
+
remove_shim,
|
|
159
|
+
reap_shims,
|
|
160
|
+
shim_path,
|
|
161
|
+
)
|
|
162
|
+
|
|
163
|
+
__version__ = '0.4.1'
|
|
142
164
|
|
|
143
165
|
def configure_logging(level=logging.INFO, log_file=None):
|
|
144
166
|
"""
|
|
@@ -300,5 +322,22 @@ __all__ = [
|
|
|
300
322
|
'save_hashes_to_file',
|
|
301
323
|
'load_hashes_from_file',
|
|
302
324
|
'compare_directories',
|
|
303
|
-
'verify_copied_files'
|
|
325
|
+
'verify_copied_files',
|
|
326
|
+
|
|
327
|
+
# long-path shims (v0.4.0)
|
|
328
|
+
'MAX_PATH',
|
|
329
|
+
'USABLE_PATH',
|
|
330
|
+
'DEFAULT_THRESHOLD',
|
|
331
|
+
'NAME_MAX',
|
|
332
|
+
'SHIM_DIR_NAME',
|
|
333
|
+
'ShimPlan',
|
|
334
|
+
'needs_shim',
|
|
335
|
+
'candidate_roots',
|
|
336
|
+
'resolve_shim_root',
|
|
337
|
+
'budget_for',
|
|
338
|
+
'plan_shim',
|
|
339
|
+
'create_shim',
|
|
340
|
+
'remove_shim',
|
|
341
|
+
'reap_shims',
|
|
342
|
+
'shim_path',
|
|
304
343
|
]
|
|
@@ -0,0 +1,526 @@
|
|
|
1
|
+
"""Long-path shims (L2).
|
|
2
|
+
|
|
3
|
+
This module answers one question: *"this path is too long for a MAX_PATH-bound
|
|
4
|
+
consumer -- what shorter path names the same bytes?"*
|
|
5
|
+
|
|
6
|
+
It exists because :func:`utils.validation.is_valid_path` already **detects** the
|
|
7
|
+
condition (it returns ``False`` for paths over 260 that lack a ``\\\\?\\`` prefix)
|
|
8
|
+
but nothing in filekit offered a remedy. This is that remedy.
|
|
9
|
+
|
|
10
|
+
Why a shim rather than the extended-length prefix
|
|
11
|
+
-------------------------------------------------
|
|
12
|
+
``\\\\?\\`` lifts the limit at the *Win32 API* layer, and that is enough for a
|
|
13
|
+
well-behaved caller. It is **not** enough for an application that builds the
|
|
14
|
+
correct extended path and then copies it into a fixed ``MAX_PATH`` buffer --
|
|
15
|
+
observed in the wild in more than one PDF reader, which truncates the tail and
|
|
16
|
+
then reports the file as missing. Nothing outside such an application can fix
|
|
17
|
+
its internal buffer. What *can* be changed is the length of the string handed
|
|
18
|
+
to it, and a directory junction at a short location does exactly that: same
|
|
19
|
+
bytes, shorter name, no cooperation required from the consumer.
|
|
20
|
+
|
|
21
|
+
Scope
|
|
22
|
+
-----
|
|
23
|
+
Windows-only in effect. ``PATH_MAX`` is 4096 on Linux and 1024 on macOS/BSD, so
|
|
24
|
+
the condition this module treats does not arise there; :func:`needs_shim`
|
|
25
|
+
returns ``False`` on POSIX and every other entry point degrades to a no-op.
|
|
26
|
+
Note that ``NAME_MAX`` is 255 on *every* platform -- a single path *component*
|
|
27
|
+
longer than that cannot be rescued by any amount of linking, because the
|
|
28
|
+
offending name must itself appear in the shimmed path. :func:`plan_shim`
|
|
29
|
+
reports that case rather than pretending to solve it.
|
|
30
|
+
|
|
31
|
+
Safety
|
|
32
|
+
------
|
|
33
|
+
Shim removal never recurses. :func:`remove_shim` re-verifies that its target is
|
|
34
|
+
a junction *immediately before* deleting (closing the check-then-act window)
|
|
35
|
+
and uses ``os.rmdir``, which removes the reparse point only. This matters
|
|
36
|
+
because every naive test misidentifies a junction: ``os.path.islink()`` is
|
|
37
|
+
``False``, ``os.path.isdir()`` is ``True``, and ``DirEntry.is_symlink()`` is
|
|
38
|
+
``False`` -- a junction presents as an ordinary directory. Deleting one
|
|
39
|
+
recursively through a careless code path would delete the target's contents.
|
|
40
|
+
"""
|
|
41
|
+
from __future__ import annotations
|
|
42
|
+
|
|
43
|
+
import ctypes
|
|
44
|
+
import hashlib
|
|
45
|
+
import logging
|
|
46
|
+
import os
|
|
47
|
+
import time
|
|
48
|
+
from dataclasses import dataclass, field
|
|
49
|
+
from pathlib import Path
|
|
50
|
+
from typing import List, Optional, Sequence, Union
|
|
51
|
+
|
|
52
|
+
from .links import create_junction, read_link_target
|
|
53
|
+
from .utils.validation import is_junction
|
|
54
|
+
|
|
55
|
+
logger = logging.getLogger(__name__)
|
|
56
|
+
|
|
57
|
+
#: The Windows legacy path limit, inclusive of the terminating NUL.
|
|
58
|
+
MAX_PATH = 260
|
|
59
|
+
|
|
60
|
+
#: Longest path a MAX_PATH-bound consumer can actually hold (260 minus the NUL).
|
|
61
|
+
USABLE_PATH = 259
|
|
62
|
+
|
|
63
|
+
#: Default trigger length. Deliberately below :data:`USABLE_PATH`: some handlers
|
|
64
|
+
#: append to the path they are given (a ``.tmp`` suffix, a backup name), so a
|
|
65
|
+
#: path that merely *fits* can still overflow once the consumer touches it.
|
|
66
|
+
DEFAULT_THRESHOLD = 240
|
|
67
|
+
|
|
68
|
+
#: Longest single filename permitted by NTFS and by POSIX ``NAME_MAX`` alike.
|
|
69
|
+
NAME_MAX = 255
|
|
70
|
+
|
|
71
|
+
#: Directory name used for shim roots. Short by design -- every character here
|
|
72
|
+
#: is one taken away from the filename it has to accommodate.
|
|
73
|
+
SHIM_DIR_NAME = ".dzs"
|
|
74
|
+
|
|
75
|
+
#: Starting length of the generated per-anchor id, extended on collision.
|
|
76
|
+
_ID_LEN = 4
|
|
77
|
+
|
|
78
|
+
_EXTENDED_PREFIXES = ("\\\\?\\", "\\\\.\\")
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def _is_windows() -> bool:
|
|
82
|
+
return os.name == "nt"
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def needs_shim(path: Union[str, Path],
|
|
86
|
+
threshold: int = DEFAULT_THRESHOLD) -> bool:
|
|
87
|
+
"""Return ``True`` when *path* is long enough to break a MAX_PATH consumer.
|
|
88
|
+
|
|
89
|
+
Returns ``False`` on non-Windows platforms, and ``False`` for a path that
|
|
90
|
+
already carries an extended-length prefix (such a path has opted out of the
|
|
91
|
+
limit and rewriting it would be pointless).
|
|
92
|
+
"""
|
|
93
|
+
if not _is_windows():
|
|
94
|
+
return False
|
|
95
|
+
text = str(path)
|
|
96
|
+
if text.startswith(_EXTENDED_PREFIXES):
|
|
97
|
+
return False
|
|
98
|
+
return len(text) > threshold
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def candidate_roots(target: Optional[Union[str, Path]] = None) -> List[Path]:
|
|
102
|
+
"""Ordered shim-root candidates, shortest first.
|
|
103
|
+
|
|
104
|
+
The root's own length is subtracted from the budget available to the
|
|
105
|
+
filename, so this order is not cosmetic. A 49-character root
|
|
106
|
+
(``%LOCALAPPDATA%\\dazzlecmd\\longpath``) leaves a 244-character filename
|
|
107
|
+
needing 294 characters and still broken; a 7-character root does not.
|
|
108
|
+
|
|
109
|
+
``%USERPROFILE%`` is included because it is the one location guaranteed
|
|
110
|
+
writable, but it is deliberately ranked below the drive roots: its length
|
|
111
|
+
varies with the username, so the same code serves every file on one machine
|
|
112
|
+
and silently drops the longest ones on another.
|
|
113
|
+
"""
|
|
114
|
+
roots: List[Path] = []
|
|
115
|
+
|
|
116
|
+
if target is not None:
|
|
117
|
+
drive = os.path.splitdrive(os.path.abspath(str(target)))[0]
|
|
118
|
+
if drive:
|
|
119
|
+
roots.append(Path(drive + os.sep) / SHIM_DIR_NAME)
|
|
120
|
+
|
|
121
|
+
# A present-but-empty SystemDrive would yield a drive-*relative* ``\.dzs``,
|
|
122
|
+
# which resolves against whatever drive happens to be current at runtime --
|
|
123
|
+
# a root that moves under the caller. Guarding only falsy values is not
|
|
124
|
+
# enough: a truthy-but-malformed value ("C" without its colon, or pure
|
|
125
|
+
# whitespace) is equally degenerate. Validate the result is genuinely
|
|
126
|
+
# absolute and fall back to C: when it is not.
|
|
127
|
+
system_drive = (os.environ.get("SystemDrive") or "").strip()
|
|
128
|
+
system_root = Path(system_drive + os.sep) if system_drive else None
|
|
129
|
+
if system_root is None or not system_root.is_absolute():
|
|
130
|
+
system_root = Path("C:" + os.sep)
|
|
131
|
+
roots.append(system_root / SHIM_DIR_NAME)
|
|
132
|
+
|
|
133
|
+
for env in ("USERPROFILE", "HOME", "TEMP", "TMP"):
|
|
134
|
+
value = os.environ.get(env)
|
|
135
|
+
if value:
|
|
136
|
+
roots.append(Path(value) / SHIM_DIR_NAME)
|
|
137
|
+
|
|
138
|
+
seen, ordered = set(), []
|
|
139
|
+
for r in roots:
|
|
140
|
+
key = str(r).casefold()
|
|
141
|
+
if key not in seen:
|
|
142
|
+
seen.add(key)
|
|
143
|
+
ordered.append(r)
|
|
144
|
+
return ordered
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
def _probe_writable(root: Path) -> bool:
|
|
148
|
+
"""Can we create *root* and a directory inside it? Cleans up after itself.
|
|
149
|
+
|
|
150
|
+
A child directory is probed, not just the root: the shim itself is created
|
|
151
|
+
as a child, so root-writability alone would not prove what we need.
|
|
152
|
+
"""
|
|
153
|
+
created_root = False
|
|
154
|
+
probe = root / "_w"
|
|
155
|
+
try:
|
|
156
|
+
if not root.exists():
|
|
157
|
+
root.mkdir(parents=True)
|
|
158
|
+
created_root = True
|
|
159
|
+
probe.mkdir(exist_ok=True)
|
|
160
|
+
return True
|
|
161
|
+
except OSError:
|
|
162
|
+
return False
|
|
163
|
+
finally:
|
|
164
|
+
try:
|
|
165
|
+
if probe.is_dir() and not is_junction(probe):
|
|
166
|
+
os.rmdir(probe)
|
|
167
|
+
if created_root and root.is_dir() and not any(root.iterdir()):
|
|
168
|
+
os.rmdir(root)
|
|
169
|
+
except OSError:
|
|
170
|
+
pass
|
|
171
|
+
|
|
172
|
+
|
|
173
|
+
def resolve_shim_root(target: Optional[Union[str, Path]] = None,
|
|
174
|
+
candidates: Optional[Sequence[Path]] = None,
|
|
175
|
+
probe: bool = True) -> Optional[Path]:
|
|
176
|
+
"""Return the shortest writable shim root, or ``None`` if none is usable.
|
|
177
|
+
|
|
178
|
+
With ``probe=False`` the first candidate is returned unchecked, which is
|
|
179
|
+
what tests want when they are exercising the ordering rather than the
|
|
180
|
+
filesystem.
|
|
181
|
+
"""
|
|
182
|
+
if not _is_windows():
|
|
183
|
+
return None
|
|
184
|
+
for root in (candidates if candidates is not None else candidate_roots(target)):
|
|
185
|
+
if not probe or _probe_writable(Path(root)):
|
|
186
|
+
return Path(root)
|
|
187
|
+
return None
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
def budget_for(root: Union[str, Path], id_len: int = _ID_LEN) -> int:
|
|
191
|
+
"""Longest filename a shim under *root* can serve.
|
|
192
|
+
|
|
193
|
+
``<root>\\<id>\\<filename>`` must fit in :data:`USABLE_PATH`.
|
|
194
|
+
"""
|
|
195
|
+
return USABLE_PATH - (len(str(root)) + 1 + id_len + 1)
|
|
196
|
+
|
|
197
|
+
|
|
198
|
+
def _anchor_id(anchor: Path, length: int = _ID_LEN) -> str:
|
|
199
|
+
"""Stable short id for an anchor directory, so repeat opens reuse one shim.
|
|
200
|
+
|
|
201
|
+
Case-folded because Windows paths are case-insensitive: two spellings of
|
|
202
|
+
the same directory must not mint two junctions.
|
|
203
|
+
"""
|
|
204
|
+
digest = hashlib.sha256(str(anchor).casefold().encode("utf-8")).hexdigest()
|
|
205
|
+
return digest[:length]
|
|
206
|
+
|
|
207
|
+
|
|
208
|
+
@dataclass
|
|
209
|
+
class ShimPlan:
|
|
210
|
+
"""What (if anything) must exist for *original* to be openable."""
|
|
211
|
+
|
|
212
|
+
original: Path
|
|
213
|
+
needed: bool
|
|
214
|
+
anchor: Optional[Path] = None # directory to be junctioned
|
|
215
|
+
link: Optional[Path] = None # where the junction goes
|
|
216
|
+
shimmed: Optional[Path] = None # rewritten path to hand to the consumer
|
|
217
|
+
reason: str = ""
|
|
218
|
+
warnings: List[str] = field(default_factory=list)
|
|
219
|
+
|
|
220
|
+
@property
|
|
221
|
+
def usable(self) -> bool:
|
|
222
|
+
"""True when this plan yields a path a MAX_PATH consumer can open."""
|
|
223
|
+
return self.shimmed is not None
|
|
224
|
+
|
|
225
|
+
def resolved(self) -> Path:
|
|
226
|
+
"""The path to hand onward -- shimmed when possible, else the original.
|
|
227
|
+
|
|
228
|
+
Never raises. A consumer that cannot be helped is still given its
|
|
229
|
+
original path, so the caller degrades to today's behaviour rather than
|
|
230
|
+
failing outright.
|
|
231
|
+
"""
|
|
232
|
+
return self.shimmed if self.shimmed is not None else self.original
|
|
233
|
+
|
|
234
|
+
|
|
235
|
+
def plan_shim(path: Union[str, Path],
|
|
236
|
+
root: Optional[Union[str, Path]] = None,
|
|
237
|
+
threshold: int = DEFAULT_THRESHOLD,
|
|
238
|
+
id_len: int = _ID_LEN) -> ShimPlan:
|
|
239
|
+
"""Decide how to shorten *path*, without touching the filesystem.
|
|
240
|
+
|
|
241
|
+
Chooses the **shallowest** ancestor directory whose junction still brings
|
|
242
|
+
the result under :data:`USABLE_PATH`. Shallowest rather than deepest so one
|
|
243
|
+
shim covers as much of the tree as possible and repeat opens reuse it;
|
|
244
|
+
where the filename is long enough that only its immediate parent fits, that
|
|
245
|
+
is what gets chosen.
|
|
246
|
+
"""
|
|
247
|
+
original = Path(path)
|
|
248
|
+
|
|
249
|
+
if not needs_shim(original, threshold):
|
|
250
|
+
return ShimPlan(original=original, needed=False, reason="under threshold")
|
|
251
|
+
|
|
252
|
+
name = original.name
|
|
253
|
+
if len(name) > NAME_MAX:
|
|
254
|
+
return ShimPlan(
|
|
255
|
+
original=original, needed=True,
|
|
256
|
+
reason="filename exceeds NAME_MAX (%d > %d) -- no link can shorten "
|
|
257
|
+
"a single component" % (len(name), NAME_MAX),
|
|
258
|
+
)
|
|
259
|
+
|
|
260
|
+
if root is None:
|
|
261
|
+
root = resolve_shim_root(original)
|
|
262
|
+
if root is None:
|
|
263
|
+
return ShimPlan(original=original, needed=True,
|
|
264
|
+
reason="no writable shim root available")
|
|
265
|
+
root = Path(root)
|
|
266
|
+
|
|
267
|
+
parent = original.parent
|
|
268
|
+
ancestors = [parent] + list(parent.parents) # deepest first
|
|
269
|
+
ancestors.reverse() # shallowest first
|
|
270
|
+
|
|
271
|
+
warnings: List[str] = []
|
|
272
|
+
for anchor in ancestors:
|
|
273
|
+
try:
|
|
274
|
+
rel = original.relative_to(anchor)
|
|
275
|
+
except ValueError: # pragma: no cover - defensive
|
|
276
|
+
continue
|
|
277
|
+
link = root / _anchor_id(anchor, id_len)
|
|
278
|
+
shimmed = link / rel
|
|
279
|
+
if len(str(shimmed)) <= USABLE_PATH:
|
|
280
|
+
return ShimPlan(original=original, needed=True, anchor=anchor,
|
|
281
|
+
link=link, shimmed=shimmed,
|
|
282
|
+
reason="anchored at %s" % anchor,
|
|
283
|
+
warnings=warnings)
|
|
284
|
+
|
|
285
|
+
return ShimPlan(
|
|
286
|
+
original=original, needed=True,
|
|
287
|
+
reason="no anchor fits: shim root %r is %d chars, leaving %d for a "
|
|
288
|
+
"%d-char filename" % (str(root), len(str(root)),
|
|
289
|
+
budget_for(root, id_len), len(name)),
|
|
290
|
+
warnings=warnings,
|
|
291
|
+
)
|
|
292
|
+
|
|
293
|
+
|
|
294
|
+
def _same_dir(a: Union[str, Path, None], b: Union[str, Path, None]) -> bool:
|
|
295
|
+
"""Do two path strings name the same directory?
|
|
296
|
+
|
|
297
|
+
Windows-aware: case-insensitive, tolerant of trailing separators, and of
|
|
298
|
+
the ``\\\\?\\`` / ``\\\\?\\UNC\\`` forms the kernel may hand back from a
|
|
299
|
+
reparse buffer even when the link was created from a plain path.
|
|
300
|
+
"""
|
|
301
|
+
if a is None or b is None:
|
|
302
|
+
return False
|
|
303
|
+
|
|
304
|
+
def norm(p: Union[str, Path]) -> str:
|
|
305
|
+
s = str(p)
|
|
306
|
+
for prefix in _EXTENDED_PREFIXES:
|
|
307
|
+
if s.startswith(prefix):
|
|
308
|
+
s = s[len(prefix):]
|
|
309
|
+
if s.upper().startswith("UNC\\"):
|
|
310
|
+
s = "\\\\" + s[4:]
|
|
311
|
+
break
|
|
312
|
+
s = os.path.normcase(os.path.normpath(s))
|
|
313
|
+
# Strip a trailing separator, but never the one that distinguishes a
|
|
314
|
+
# drive ROOT from a drive-RELATIVE path: ``C:\`` and ``C:`` name
|
|
315
|
+
# different things to Windows (``Path("C:") == Path("C:\\")`` is
|
|
316
|
+
# False), and a blanket rstrip collapses them onto each other.
|
|
317
|
+
drive, rest = os.path.splitdrive(s)
|
|
318
|
+
if rest.strip("\\/"):
|
|
319
|
+
rest = rest.rstrip("\\/")
|
|
320
|
+
return drive + rest
|
|
321
|
+
|
|
322
|
+
return norm(a) == norm(b)
|
|
323
|
+
|
|
324
|
+
|
|
325
|
+
def create_shim(plan: ShimPlan, max_id_len: int = 16) -> bool:
|
|
326
|
+
"""Materialise *plan*'s junction, reusing an existing one for the same anchor.
|
|
327
|
+
|
|
328
|
+
**Anchor ids collide.** The id is a truncated hash, so two unrelated
|
|
329
|
+
directories can map to the same link name -- at the 4-character default
|
|
330
|
+
that is an even chance somewhere around three hundred distinct anchors, not
|
|
331
|
+
a remote possibility on a large library. An earlier version treated *any*
|
|
332
|
+
junction at the expected link as proof of a previous mint for this anchor
|
|
333
|
+
and returned success; on a collision the caller then read a **different
|
|
334
|
+
directory's** file, silently and with no error. Whether an existing
|
|
335
|
+
junction points at *our* anchor is therefore verified, not assumed, and a
|
|
336
|
+
collision is resolved by lengthening the id until a matching or free slot
|
|
337
|
+
is found.
|
|
338
|
+
|
|
339
|
+
On success the plan's ``link`` and ``shimmed`` are updated to whatever was
|
|
340
|
+
actually used, so a caller that reads ``plan.shimmed`` afterwards is never
|
|
341
|
+
handed a path the collision loop moved away from.
|
|
342
|
+
"""
|
|
343
|
+
if not plan.needed or plan.link is None or plan.anchor is None:
|
|
344
|
+
return False
|
|
345
|
+
|
|
346
|
+
anchor = Path(plan.anchor)
|
|
347
|
+
requested = Path(plan.link)
|
|
348
|
+
root = requested.parent
|
|
349
|
+
try:
|
|
350
|
+
rel = Path(plan.original).relative_to(anchor)
|
|
351
|
+
except ValueError: # pragma: no cover - defensive
|
|
352
|
+
return False
|
|
353
|
+
|
|
354
|
+
# The requested link is always tried first -- ``plan.link`` is a contract,
|
|
355
|
+
# not a hint. Longer-id alternates exist only to escape a genuine hash
|
|
356
|
+
# collision, and are never used to relocate a shim the caller sited itself.
|
|
357
|
+
candidates = [requested]
|
|
358
|
+
candidates.extend(root / _anchor_id(anchor, n)
|
|
359
|
+
for n in range(_ID_LEN + 1, max_id_len + 1))
|
|
360
|
+
|
|
361
|
+
for link in candidates:
|
|
362
|
+
shimmed = link / rel
|
|
363
|
+
|
|
364
|
+
# A longer id costs characters; never trade a collision fix for an
|
|
365
|
+
# over-length path, which would defeat the point of the shim entirely.
|
|
366
|
+
if len(str(shimmed)) > USABLE_PATH:
|
|
367
|
+
logger.warning("cannot place a shim for %s without exceeding "
|
|
368
|
+
"MAX_PATH", anchor)
|
|
369
|
+
return False
|
|
370
|
+
|
|
371
|
+
if is_junction(link):
|
|
372
|
+
if _same_dir(read_link_target(link), anchor):
|
|
373
|
+
plan.link, plan.shimmed = link, shimmed
|
|
374
|
+
return True
|
|
375
|
+
# Someone else's anchor holds this id. Try a longer one rather than
|
|
376
|
+
# returning success for a junction pointing somewhere else.
|
|
377
|
+
logger.debug("shim id collision at %s -- lengthening id", link)
|
|
378
|
+
continue
|
|
379
|
+
|
|
380
|
+
if link.exists():
|
|
381
|
+
# Occupied by a real file or directory. Deliberately NOT worked
|
|
382
|
+
# around: the caller named this location, and quietly siting the
|
|
383
|
+
# shim elsewhere would be more surprising than failing.
|
|
384
|
+
logger.warning("shim path occupied by a non-junction: %s", link)
|
|
385
|
+
return False
|
|
386
|
+
|
|
387
|
+
try:
|
|
388
|
+
root.mkdir(parents=True, exist_ok=True)
|
|
389
|
+
except (OSError, ValueError) as exc:
|
|
390
|
+
# ValueError, not OSError, is what Path.mkdir raises for an
|
|
391
|
+
# embedded NUL -- catching only OSError let it escape a caller
|
|
392
|
+
# documented never to raise.
|
|
393
|
+
logger.error("cannot create shim root %s: %s", root, exc)
|
|
394
|
+
return False
|
|
395
|
+
|
|
396
|
+
# The return value is ADVISORY; what matters is what is on disk
|
|
397
|
+
# afterwards. `create_junction` checks `link.exists()` and only then
|
|
398
|
+
# shells out to PowerShell, so two callers can both pass that check --
|
|
399
|
+
# and `New-Item -ItemType Junction` will replace an existing reparse
|
|
400
|
+
# point, so the loser of that race can silently overwrite the winner's
|
|
401
|
+
# junction with a different target. Trusting a True here is how a
|
|
402
|
+
# caller ends up reading someone else's directory.
|
|
403
|
+
create_junction(anchor, link)
|
|
404
|
+
|
|
405
|
+
if is_junction(link):
|
|
406
|
+
if _same_dir(read_link_target(link), anchor):
|
|
407
|
+
plan.link, plan.shimmed = link, shimmed
|
|
408
|
+
return True
|
|
409
|
+
# Either another anchor won the race, or ours was replaced after
|
|
410
|
+
# we made it. Advance to a longer id instead of giving up: the
|
|
411
|
+
# remaining candidates were never tried.
|
|
412
|
+
logger.debug("lost a shim creation race at %s -- lengthening id",
|
|
413
|
+
link)
|
|
414
|
+
continue
|
|
415
|
+
|
|
416
|
+
if link.exists():
|
|
417
|
+
continue # a non-junction landed here; try the next id
|
|
418
|
+
|
|
419
|
+
return False # nothing was created -- a genuine failure
|
|
420
|
+
|
|
421
|
+
logger.warning("exhausted shim ids up to %d chars for %s", max_id_len, anchor)
|
|
422
|
+
return False
|
|
423
|
+
|
|
424
|
+
|
|
425
|
+
def remove_shim(link: Union[str, Path]) -> bool:
|
|
426
|
+
"""Remove a shim junction, leaving its target untouched.
|
|
427
|
+
|
|
428
|
+
**Refuses anything that is not a junction.** The check is made immediately
|
|
429
|
+
before the delete rather than trusted from an earlier scan, so a directory
|
|
430
|
+
swapped in after a listing is not removed.
|
|
431
|
+
|
|
432
|
+
That **narrows** the check-then-act window; it does not close it. The check
|
|
433
|
+
and the delete remain two calls, and there is no atomic "unlink only if
|
|
434
|
+
still a reparse point" primitive to use instead. Measured consequence of
|
|
435
|
+
the surviving race: if a real directory replaces the junction between the
|
|
436
|
+
two calls, ``os.rmdir`` deletes it when it is **empty** and refuses it when
|
|
437
|
+
it is **not** -- so the blast radius is bounded to an empty directory, and
|
|
438
|
+
no file contents can be lost through this path.
|
|
439
|
+
|
|
440
|
+
Uses ``os.rmdir``, which unlinks the reparse point without descending into
|
|
441
|
+
it. Never call a recursive remove on a shim: a junction is reported as an
|
|
442
|
+
ordinary directory by ``os.path.islink``, ``os.path.isdir`` and
|
|
443
|
+
``DirEntry.is_symlink``, so a recursive shell delete will happily walk into
|
|
444
|
+
the real data.
|
|
445
|
+
"""
|
|
446
|
+
p = Path(link)
|
|
447
|
+
if not is_junction(p):
|
|
448
|
+
logger.debug("refusing to remove non-junction: %s", p)
|
|
449
|
+
return False
|
|
450
|
+
try:
|
|
451
|
+
os.rmdir(p) # reparse point only -- never the target contents
|
|
452
|
+
return True
|
|
453
|
+
except OSError as exc:
|
|
454
|
+
logger.warning("could not remove shim %s: %s", p, exc)
|
|
455
|
+
return False
|
|
456
|
+
|
|
457
|
+
|
|
458
|
+
def reap_shims(root: Union[str, Path],
|
|
459
|
+
max_age_seconds: float = 86400.0,
|
|
460
|
+
now: Optional[float] = None) -> List[Path]:
|
|
461
|
+
"""Remove shims under *root* older than *max_age_seconds*.
|
|
462
|
+
|
|
463
|
+
Only junctions are considered; anything else in the directory is left
|
|
464
|
+
alone. Returns the shims actually removed.
|
|
465
|
+
"""
|
|
466
|
+
root = Path(root)
|
|
467
|
+
if not root.is_dir():
|
|
468
|
+
return []
|
|
469
|
+
|
|
470
|
+
now = time.time() if now is None else now
|
|
471
|
+
removed: List[Path] = []
|
|
472
|
+
|
|
473
|
+
try:
|
|
474
|
+
entries = list(os.scandir(root))
|
|
475
|
+
except OSError:
|
|
476
|
+
return removed
|
|
477
|
+
|
|
478
|
+
for entry in entries:
|
|
479
|
+
candidate = Path(entry.path)
|
|
480
|
+
if not is_junction(candidate):
|
|
481
|
+
continue
|
|
482
|
+
try:
|
|
483
|
+
age = now - entry.stat(follow_symlinks=False).st_mtime
|
|
484
|
+
except OSError:
|
|
485
|
+
continue
|
|
486
|
+
if age >= max_age_seconds and remove_shim(candidate):
|
|
487
|
+
removed.append(candidate)
|
|
488
|
+
|
|
489
|
+
return removed
|
|
490
|
+
|
|
491
|
+
|
|
492
|
+
def shim_path(path: Union[str, Path],
|
|
493
|
+
root: Optional[Union[str, Path]] = None,
|
|
494
|
+
threshold: int = DEFAULT_THRESHOLD) -> Path:
|
|
495
|
+
"""Convenience: return an openable path for *path*, creating a shim if needed.
|
|
496
|
+
|
|
497
|
+
Falls back to the original path whenever a shim is unnecessary, impossible,
|
|
498
|
+
or fails to materialise -- so a caller is never left worse off than if this
|
|
499
|
+
module did not exist.
|
|
500
|
+
|
|
501
|
+
**Never raises for a path-shaped input.** The whole body is guarded, and
|
|
502
|
+
the guard has to be wider than it first looks. A malformed *root* -- an
|
|
503
|
+
embedded NUL, say -- surfaces differently depending on the interpreter:
|
|
504
|
+
on 3.12+ :func:`utils.validation.is_junction` delegates to
|
|
505
|
+
``os.path.isjunction`` and the failure arrives as ``ValueError``, while on
|
|
506
|
+
3.9-3.11 it falls back to a ctypes ``DeviceIoControl`` call and the same
|
|
507
|
+
condition arrives as ``ctypes.ArgumentError``, which derives from
|
|
508
|
+
``Exception`` and not from ``ValueError``. Catching only the latter passes
|
|
509
|
+
every test on a 3.13 dev box and raises on a 3.10 CI runner.
|
|
510
|
+
|
|
511
|
+
A caller substituting this for a bare path must not have to grow an
|
|
512
|
+
exception handler it did not previously need.
|
|
513
|
+
"""
|
|
514
|
+
try:
|
|
515
|
+
plan = plan_shim(path, root=root, threshold=threshold)
|
|
516
|
+
if not plan.needed:
|
|
517
|
+
return plan.original
|
|
518
|
+
if plan.usable and create_shim(plan):
|
|
519
|
+
return plan.shimmed
|
|
520
|
+
if plan.reason:
|
|
521
|
+
logger.debug("no shim for %s: %s", path, plan.reason)
|
|
522
|
+
return plan.original
|
|
523
|
+
except (OSError, ValueError, ctypes.ArgumentError) as exc:
|
|
524
|
+
logger.warning("shim_path fell back to the original path for %r: %s",
|
|
525
|
+
path, exc)
|
|
526
|
+
return Path(path)
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: dazzle-filekit
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.4.1
|
|
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>
|
|
@@ -44,7 +44,7 @@ Dynamic: requires-python
|
|
|
44
44
|
|
|
45
45
|
[](https://github.com/DazzleLib/dazzle-filekit/releases)
|
|
46
46
|
[](https://pypi.org/project/dazzle-filekit/)
|
|
47
|
-
[](https://
|
|
47
|
+
[](https://pypistats.org/packages/dazzle-filekit)
|
|
48
48
|
[](https://www.python.org/downloads/)
|
|
49
49
|
[](https://opensource.org/licenses/MIT)
|
|
50
50
|
[](https://github.com/DazzleLib/dazzle-filekit/discussions)
|
|
@@ -68,6 +68,7 @@ A Python toolkit for reliable file operations across Windows, Linux, and macOS.
|
|
|
68
68
|
- **Platform Support** - Windows, Linux, and macOS with platform-specific optimizations
|
|
69
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
70
|
- **Link Primitives** - `analyze_link` / `create_junction` / `create_hardlink` / `read_link_target` (intrinsic link analysis; junctions via PowerShell, no `cmd`)
|
|
71
|
+
- **Long-Path Shims** - `shim_path` makes a file over Windows' 260-character `MAX_PATH` openable by *any* application, by siting a junction at a short root and handing back a shorter name for the same bytes. `\\?\` only lifts the limit at the API layer; it does not help an app that copies the path into a fixed 260-byte buffer (observed in two PDF readers), and nothing outside such an app can fix its buffer. A no-op on Linux/macOS, where `PATH_MAX` is 4096/1024
|
|
71
72
|
|
|
72
73
|
## Why dazzle-filekit?
|
|
73
74
|
|
|
@@ -270,6 +271,7 @@ For the full function-by-function reference, see
|
|
|
270
271
|
| **Verification** | `calculate_file_hash`, `verify_file_hash`, `verify_files_with_manifest`, `compare_directories` |
|
|
271
272
|
| **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
273
|
| **Link primitives** | `analyze_link`, `detect_link_type`, `read_link_target`, `create_junction`, `create_hardlink` |
|
|
274
|
+
| **Long paths** | `dazzle_filekit.longpath` -- `shim_path` (one-call), `needs_shim`, `plan_shim`, `resolve_shim_root`, `budget_for`, `create_shim`, `remove_shim`, `reap_shims` |
|
|
273
275
|
|
|
274
276
|
## Platform Support
|
|
275
277
|
|