dazzle-filekit 0.3.0__tar.gz → 0.3.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 (45) hide show
  1. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/PKG-INFO +1 -1
  2. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/dazzle_filekit/__init__.py +1 -1
  3. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/dazzle_filekit/metadata.py +97 -14
  4. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/dazzle_filekit/paths.py +11 -6
  5. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/dazzle_filekit/utils/validation.py +6 -5
  6. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/dazzle_filekit.egg-info/PKG-INFO +1 -1
  7. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/dazzle_filekit.egg-info/SOURCES.txt +2 -1
  8. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/pyproject.toml +1 -1
  9. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/setup.py +1 -1
  10. dazzle_filekit-0.3.1/tests/test_symlink_timestamps_v031.py +68 -0
  11. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/LICENSE +0 -0
  12. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/README.md +0 -0
  13. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/dazzle_filekit/_fallback.py +0 -0
  14. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/dazzle_filekit/content.py +0 -0
  15. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/dazzle_filekit/links.py +0 -0
  16. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/dazzle_filekit/operations.py +0 -0
  17. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/dazzle_filekit/platform/__init__.py +0 -0
  18. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/dazzle_filekit/platform/unix.py +0 -0
  19. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/dazzle_filekit/platform/windows.py +0 -0
  20. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/dazzle_filekit/utils/__init__.py +0 -0
  21. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/dazzle_filekit/utils/compat.py +0 -0
  22. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/dazzle_filekit/utils/disk.py +0 -0
  23. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/dazzle_filekit/utils/logger.py +0 -0
  24. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/dazzle_filekit/verification.py +0 -0
  25. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/dazzle_filekit.egg-info/dependency_links.txt +0 -0
  26. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/dazzle_filekit.egg-info/requires.txt +0 -0
  27. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/dazzle_filekit.egg-info/top_level.txt +0 -0
  28. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/setup.cfg +0 -0
  29. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/tests/test_ads_and_junction_v024.py +0 -0
  30. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/tests/test_auto_naming.py +0 -0
  31. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/tests/test_compat.py +0 -0
  32. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/tests/test_content_and_process.py +0 -0
  33. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/tests/test_disk.py +0 -0
  34. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/tests/test_fallback.py +0 -0
  35. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/tests/test_import_stability.py +0 -0
  36. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/tests/test_link_primitives.py +0 -0
  37. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/tests/test_metadata_v024_roundtrip.py +0 -0
  38. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/tests/test_operations_primitives_v024.py +0 -0
  39. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/tests/test_paths_platform_simulation.py +0 -0
  40. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/tests/test_paths_v024_enrichments.py +0 -0
  41. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/tests/test_phase_b_absorb_and_v9.py +0 -0
  42. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/tests/test_phase_c_renames.py +0 -0
  43. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/tests/test_phase_d_typeddicts.py +0 -0
  44. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/tests/test_resolver_ops.py +0 -0
  45. {dazzle_filekit-0.3.0 → dazzle_filekit-0.3.1}/tests/test_smoke.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: dazzle-filekit
3
- Version: 0.3.0
3
+ Version: 0.3.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>
@@ -118,7 +118,7 @@ from .links import (
118
118
  create_hardlink,
119
119
  )
120
120
 
121
- __version__ = '0.3.0'
121
+ __version__ = '0.3.1'
122
122
 
123
123
  def configure_logging(level=logging.INFO, log_file=None):
124
124
  """
@@ -194,6 +194,78 @@ def _collect_windows_metadata(path: Path) -> Dict[str, Any]:
194
194
  logger.error(f"Error collecting Windows metadata for {path}: {e}")
195
195
  return windows_metadata
196
196
 
197
+ def _set_symlink_timestamps(path_obj: Path, timestamps: Dict[str, Any]) -> bool:
198
+ """Apply timestamps to a symlink ITSELF, never the target it points to.
199
+
200
+ ``os.utime()`` and a default Win32 ``CreateFile`` both follow the reparse
201
+ point to the target -- so applying timestamps to a link the naive way
202
+ silently corrupts the *target's* timestamps. On Windows we open the link
203
+ with ``FILE_FLAG_OPEN_REPARSE_POINT`` and use ``SetFileTime``; on POSIX we
204
+ use ``os.utime(follow_symlinks=False)``. Best-effort: returns False (with a
205
+ warning) when the platform/runtime can't set link timestamps -- it never
206
+ falls back to touching the target.
207
+ """
208
+ accessed = timestamps.get('accessed')
209
+ modified = timestamps.get('modified')
210
+ created = timestamps.get('created')
211
+
212
+ if platform.system() != 'Windows':
213
+ if (os.utime in os.supports_follow_symlinks
214
+ and accessed is not None and modified is not None):
215
+ try:
216
+ os.utime(path_obj, (accessed, modified), follow_symlinks=False)
217
+ return True
218
+ except Exception as e:
219
+ logger.warning(f"Error applying symlink timestamps to {path_obj}: {e}")
220
+ return False
221
+ logger.warning(
222
+ f"Cannot set link timestamps for {path_obj} on this platform without "
223
+ f"following to the target; skipped."
224
+ )
225
+ return False
226
+
227
+ # Windows: open the link itself (FILE_FLAG_OPEN_REPARSE_POINT) + SetFileTime.
228
+ if not is_win32_available():
229
+ logger.warning(
230
+ f"pywin32 unavailable; cannot set link timestamps for {path_obj} "
231
+ f"without following to the target; skipped."
232
+ )
233
+ return False
234
+ try:
235
+ import win32file
236
+ import win32con
237
+ import pywintypes
238
+
239
+ FILE_WRITE_ATTRIBUTES = 0x100
240
+ FILE_FLAG_OPEN_REPARSE_POINT = 0x00200000
241
+
242
+ def _wt(value):
243
+ if value is None:
244
+ return None
245
+ dt = (datetime.datetime.fromtimestamp(value)
246
+ if isinstance(value, (int, float)) else value)
247
+ return pywintypes.Time(dt)
248
+
249
+ handle = win32file.CreateFile(
250
+ str(path_obj),
251
+ FILE_WRITE_ATTRIBUTES,
252
+ win32con.FILE_SHARE_READ | win32con.FILE_SHARE_WRITE,
253
+ None,
254
+ win32con.OPEN_EXISTING,
255
+ FILE_FLAG_OPEN_REPARSE_POINT | win32con.FILE_FLAG_BACKUP_SEMANTICS,
256
+ None,
257
+ )
258
+ try:
259
+ # SetFileTime(handle, creation, access, write) -- None leaves unchanged.
260
+ win32file.SetFileTime(handle, _wt(created), _wt(accessed), _wt(modified))
261
+ finally:
262
+ handle.close()
263
+ return True
264
+ except Exception as e:
265
+ logger.warning(f"Error applying symlink timestamps to {path_obj}: {e}")
266
+ return False
267
+
268
+
197
269
  def apply_file_metadata(path: Union[str, Path], metadata: FileMetadataDict) -> bool:
198
270
  """
199
271
  Apply metadata to a file.
@@ -217,23 +289,30 @@ def apply_file_metadata(path: Union[str, Path], metadata: FileMetadataDict) -> b
217
289
  logger.warning(f"Error applying permissions to {path}: {e}")
218
290
  success = False
219
291
 
220
- # Apply timestamps (mtime and atime via os.utime)
292
+ # Apply timestamps. Symlinks need special handling: os.utime() and the
293
+ # default Win32 handle follow the reparse point and would write to the
294
+ # TARGET, so route links through a link-targeting helper that sets all
295
+ # three times on the link itself.
221
296
  if 'timestamps' in metadata:
222
297
  timestamps = metadata['timestamps']
223
- try:
224
- os.utime(
225
- path_obj,
226
- (timestamps['accessed'], timestamps['modified'])
227
- )
228
- except Exception as e:
229
- logger.warning(f"Error applying timestamps to {path}: {e}")
230
- success = False
298
+ if path_obj.is_symlink():
299
+ if not _set_symlink_timestamps(path_obj, timestamps):
300
+ success = False
301
+ else:
302
+ try:
303
+ os.utime(
304
+ path_obj,
305
+ (timestamps['accessed'], timestamps['modified'])
306
+ )
307
+ except Exception as e:
308
+ logger.warning(f"Error applying timestamps to {path}: {e}")
309
+ success = False
231
310
 
232
- # On Windows, also restore creation time via pywin32
233
- if platform.system() == 'Windows' and 'created' in timestamps:
234
- if not restore_windows_creation_time(path_obj, timestamps['created']):
235
- # Non-fatal -- ctime restoration is best-effort
236
- pass
311
+ # On Windows, also restore creation time via pywin32
312
+ if platform.system() == 'Windows' and 'created' in timestamps:
313
+ if not restore_windows_creation_time(path_obj, timestamps['created']):
314
+ # Non-fatal -- ctime restoration is best-effort
315
+ pass
237
316
 
238
317
  # Apply platform-specific metadata
239
318
  if platform.system() == 'Windows' and 'windows' in metadata:
@@ -858,6 +937,10 @@ def restore_windows_creation_time(
858
937
  flags = win32con.FILE_FLAG_BACKUP_SEMANTICS
859
938
  else:
860
939
  flags = win32con.FILE_ATTRIBUTE_NORMAL
940
+ # Symlinks: open the link itself, not the target it points to, so the
941
+ # creation time lands on the link (otherwise CreateFile follows it).
942
+ if path_obj.is_symlink():
943
+ flags |= 0x00200000 # FILE_FLAG_OPEN_REPARSE_POINT
861
944
 
862
945
  # Handle readonly files: clear attribute, set time, restore attribute
863
946
  readonly_cleared = False
@@ -263,12 +263,17 @@ def split_drive_letter(path: Union[str, Path]) -> Tuple[str, str]:
263
263
  def is_unc_path(path: Union[str, Path]) -> bool:
264
264
  r"""Check if a path is a UNC (``\\server\share``) path.
265
265
 
266
- Canonical, platform-independent: delegates to the L0 path-identity
267
- owner ``unctools.is_unc_path``, which normalizes ``/`` -> ``\`` and
268
- then checks the ``\\`` prefix -- so ``//server/share`` is recognized on
269
- every platform. This is a strict superset of (and replaces, in 0.3.0)
270
- the previously divergent win32-only check here and the POSIX-``//``
271
- check in ``utils.validation``.
266
+ **This is a thin convenience WRAPPER**, not the canonical home. UNC
267
+ detection is a path-IDENTITY question, which the stack assigns to L0 --
268
+ so this delegates to ``unctools.is_unc_path`` (the owner). It is kept
269
+ public in filekit only as a convenience for file-operation callers, and
270
+ **may be deprecated in 0.4.0** in favour of importing
271
+ ``unctools.is_unc_path`` directly.
272
+
273
+ Behaviour (from the owner): normalizes ``/`` -> ``\`` then checks the
274
+ ``\\`` prefix, so ``//server/share`` is recognized on every platform.
275
+ 0.3.0 collapsed filekit's two previously-divergent copies (win32-only
276
+ here, POSIX-``//`` in ``utils.validation``) onto this single delegate.
272
277
  """
273
278
  from unctools import is_unc_path as _unc_is_unc_path
274
279
  return _unc_is_unc_path(path)
@@ -208,11 +208,12 @@ def is_relative_path(path: Union[str, Path]) -> bool:
208
208
  def is_unc_path(path: Union[str, Path]) -> bool:
209
209
  r"""Check if a path is a UNC (``\\server\share``) path.
210
210
 
211
- Canonical, platform-independent: delegates to the L0 path-identity
212
- owner ``unctools.is_unc_path`` (normalizes ``/`` -> ``\`` then checks
213
- the ``\\`` prefix). 0.3.0 collapsed this and ``paths.is_unc_path`` onto
214
- that single source of truth -- they previously diverged on POSIX
215
- (this returned ``//``-prefix True; ``paths`` returned False).
211
+ **Thin convenience WRAPPER** over the canonical owner
212
+ ``unctools.is_unc_path`` (UNC detection is path-identity = L0's domain).
213
+ Kept public only for convenience; **may be deprecated in 0.4.0** -- prefer
214
+ ``unctools.is_unc_path``. 0.3.0 collapsed this and ``paths.is_unc_path``
215
+ onto the single delegate (they previously diverged on POSIX: this returned
216
+ ``//``-prefix True; ``paths`` returned False).
216
217
  """
217
218
  from unctools import is_unc_path as _unc_is_unc_path
218
219
  return _unc_is_unc_path(path)
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: dazzle-filekit
3
- Version: 0.3.0
3
+ Version: 0.3.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>
@@ -39,4 +39,5 @@ tests/test_phase_b_absorb_and_v9.py
39
39
  tests/test_phase_c_renames.py
40
40
  tests/test_phase_d_typeddicts.py
41
41
  tests/test_resolver_ops.py
42
- tests/test_smoke.py
42
+ tests/test_smoke.py
43
+ tests/test_symlink_timestamps_v031.py
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "dazzle-filekit"
7
- version = "0.3.0"
7
+ version = "0.3.1"
8
8
  description = "Cross-platform file operations toolkit with path handling, verification, and metadata preservation"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.9"
@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
2
2
 
3
3
  setup(
4
4
  name="dazzle-filekit",
5
- version="0.3.0",
5
+ version="0.3.1",
6
6
  description="Cross-platform file operations toolkit with path handling, verification, and metadata preservation",
7
7
  author="Dustin",
8
8
  author_email="6962246+djdarcy@users.noreply.github.com",
@@ -0,0 +1,68 @@
1
+ """Regression tests for symlink-targeted timestamp application (v0.3.1).
2
+
3
+ Before 0.3.1, ``apply_file_metadata`` applied timestamps via ``os.utime(path)``,
4
+ which follows a symlink to its target -- so applying a record's timestamps to a
5
+ link silently corrupted the TARGET file's timestamps and left the link unchanged.
6
+ 0.3.1 routes symlinks through a link-targeting path (Windows:
7
+ ``FILE_FLAG_OPEN_REPARSE_POINT`` + ``SetFileTime``; POSIX:
8
+ ``os.utime(follow_symlinks=False)``).
9
+ """
10
+
11
+ import os
12
+
13
+ import pytest
14
+
15
+ from dazzle_filekit import apply_file_metadata
16
+
17
+
18
+ def _try_symlink(target, link):
19
+ """Create a symlink, returning False (to skip) if privileges are lacking."""
20
+ try:
21
+ os.symlink(str(target), str(link))
22
+ except (OSError, NotImplementedError):
23
+ return False
24
+ return os.path.islink(str(link))
25
+
26
+
27
+ def _link_timestamps_settable():
28
+ """POSIX needs lutimes (os.utime follow_symlinks); Windows uses Win32."""
29
+ if os.name == "nt":
30
+ return True
31
+ return os.utime in os.supports_follow_symlinks
32
+
33
+
34
+ def test_apply_timestamps_to_symlink_does_not_touch_target(tmp_path):
35
+ target = tmp_path / "target.txt"
36
+ target.write_text("payload", encoding="utf-8")
37
+ link = tmp_path / "link.txt"
38
+ if not _try_symlink(target, link):
39
+ pytest.skip("symlink creation not permitted on this platform/account")
40
+ if not _link_timestamps_settable():
41
+ pytest.skip("platform cannot set link timestamps without following")
42
+
43
+ target_before = os.lstat(str(target)).st_mtime
44
+ epoch_2020 = 1577836800.0 # 2020-01-01, clearly distinct from "now"
45
+
46
+ ok = apply_file_metadata(
47
+ str(link),
48
+ {"timestamps": {"created": epoch_2020, "modified": epoch_2020, "accessed": epoch_2020}},
49
+ )
50
+ assert ok is True
51
+
52
+ # The target must be untouched...
53
+ assert abs(os.lstat(str(target)).st_mtime - target_before) < 2
54
+ # ...and the LINK itself must have received the timestamp.
55
+ assert abs(os.lstat(str(link)).st_mtime - epoch_2020) < 2
56
+
57
+
58
+ def test_apply_timestamps_to_regular_file_still_works(tmp_path):
59
+ # Non-symlink path must be unchanged by the 0.3.1 fix.
60
+ f = tmp_path / "plain.txt"
61
+ f.write_text("x", encoding="utf-8")
62
+ epoch_2020 = 1577836800.0
63
+ ok = apply_file_metadata(
64
+ str(f),
65
+ {"timestamps": {"created": epoch_2020, "modified": epoch_2020, "accessed": epoch_2020}},
66
+ )
67
+ assert ok is True
68
+ assert abs(os.stat(str(f)).st_mtime - epoch_2020) < 2
File without changes
File without changes
File without changes