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.
Files changed (57) hide show
  1. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/PKG-INFO +4 -2
  2. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/README.md +3 -1
  3. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/__init__.py +41 -2
  4. dazzle_filekit-0.4.1/dazzle_filekit/longpath.py +526 -0
  5. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit.egg-info/PKG-INFO +4 -2
  6. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit.egg-info/SOURCES.txt +4 -0
  7. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/pyproject.toml +1 -1
  8. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/setup.py +1 -1
  9. dazzle_filekit-0.4.1/tests/test_longpath.py +314 -0
  10. dazzle_filekit-0.4.1/tests/test_longpath_adversarial.py +759 -0
  11. dazzle_filekit-0.4.1/tests/test_longpath_delta2.py +775 -0
  12. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/LICENSE +0 -0
  13. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/_fallback.py +0 -0
  14. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/content.py +0 -0
  15. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/links.py +0 -0
  16. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/metadata.py +0 -0
  17. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/operations.py +0 -0
  18. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/pathenv.py +0 -0
  19. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/paths.py +0 -0
  20. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/platform/__init__.py +0 -0
  21. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/platform/unix.py +0 -0
  22. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/platform/windows.py +0 -0
  23. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/utils/__init__.py +0 -0
  24. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/utils/compat.py +0 -0
  25. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/utils/disk.py +0 -0
  26. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/utils/logger.py +0 -0
  27. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/utils/validation.py +0 -0
  28. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit/verification.py +0 -0
  29. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit.egg-info/dependency_links.txt +0 -0
  30. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit.egg-info/requires.txt +0 -0
  31. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/dazzle_filekit.egg-info/top_level.txt +0 -0
  32. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/setup.cfg +0 -0
  33. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_ads_and_junction_v024.py +0 -0
  34. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_atomic_stream_writer.py +0 -0
  35. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_atomic_write_retry.py +0 -0
  36. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_auto_naming.py +0 -0
  37. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_compat.py +0 -0
  38. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_content_and_process.py +0 -0
  39. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_disk.py +0 -0
  40. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_fallback.py +0 -0
  41. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_import_stability.py +0 -0
  42. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_junction_detection_improvements.py +0 -0
  43. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_link_fidelity_v034.py +0 -0
  44. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_link_primitives.py +0 -0
  45. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_metadata_v024_roundtrip.py +0 -0
  46. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_native_hash_backend.py +0 -0
  47. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_operations_primitives_v024.py +0 -0
  48. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_pathenv.py +0 -0
  49. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_pathenv_edgecases.py +0 -0
  50. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_paths_platform_simulation.py +0 -0
  51. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_paths_v024_enrichments.py +0 -0
  52. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_phase_b_absorb_and_v9.py +0 -0
  53. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_phase_c_renames.py +0 -0
  54. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_phase_d_typeddicts.py +0 -0
  55. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_resolver_ops.py +0 -0
  56. {dazzle_filekit-0.3.4 → dazzle_filekit-0.4.1}/tests/test_smoke.py +0 -0
  57. {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.4
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
  [![Release Date](https://img.shields.io/github/release-date/DazzleLib/dazzle-filekit?color=green)](https://github.com/DazzleLib/dazzle-filekit/releases)
46
46
  [![PyPI](https://img.shields.io/pypi/v/dazzle-filekit?color=green)](https://pypi.org/project/dazzle-filekit/)
47
- [![PyPI Downloads](https://static.pepy.tech/personalized-badge/dazzle-filekit?period=total&units=international_system&left_color=black&right_color=green&left_text=downloads)](https://pepy.tech/projects/dazzle-filekit)
47
+ [![PyPI Downloads](https://static.pepy.tech/personalized-badge/dazzle-filekit?period=total&units=international_system&left_color=black&right_color=green&left_text=downloads)](https://pypistats.org/packages/dazzle-filekit)
48
48
  [![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
49
49
  [![License](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
50
50
  [![GitHub Discussions](https://img.shields.io/github/discussions/DazzleLib/dazzle-filekit)](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
  [![Release Date](https://img.shields.io/github/release-date/DazzleLib/dazzle-filekit?color=green)](https://github.com/DazzleLib/dazzle-filekit/releases)
4
4
  [![PyPI](https://img.shields.io/pypi/v/dazzle-filekit?color=green)](https://pypi.org/project/dazzle-filekit/)
5
- [![PyPI Downloads](https://static.pepy.tech/personalized-badge/dazzle-filekit?period=total&units=international_system&left_color=black&right_color=green&left_text=downloads)](https://pepy.tech/projects/dazzle-filekit)
5
+ [![PyPI Downloads](https://static.pepy.tech/personalized-badge/dazzle-filekit?period=total&units=international_system&left_color=black&right_color=green&left_text=downloads)](https://pypistats.org/packages/dazzle-filekit)
6
6
  [![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
7
7
  [![License](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
8
8
  [![GitHub Discussions](https://img.shields.io/github/discussions/DazzleLib/dazzle-filekit)](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
- __version__ = '0.3.4'
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.4
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
  [![Release Date](https://img.shields.io/github/release-date/DazzleLib/dazzle-filekit?color=green)](https://github.com/DazzleLib/dazzle-filekit/releases)
46
46
  [![PyPI](https://img.shields.io/pypi/v/dazzle-filekit?color=green)](https://pypi.org/project/dazzle-filekit/)
47
- [![PyPI Downloads](https://static.pepy.tech/personalized-badge/dazzle-filekit?period=total&units=international_system&left_color=black&right_color=green&left_text=downloads)](https://pepy.tech/projects/dazzle-filekit)
47
+ [![PyPI Downloads](https://static.pepy.tech/personalized-badge/dazzle-filekit?period=total&units=international_system&left_color=black&right_color=green&left_text=downloads)](https://pypistats.org/packages/dazzle-filekit)
48
48
  [![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
49
49
  [![License](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
50
50
  [![GitHub Discussions](https://img.shields.io/github/discussions/DazzleLib/dazzle-filekit)](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