dazzle-filekit 0.2.2__tar.gz → 0.2.4__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 (36) hide show
  1. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/PKG-INFO +100 -51
  2. dazzle_filekit-0.2.4/README.md +314 -0
  3. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/dazzle_filekit/__init__.py +35 -3
  4. dazzle_filekit-0.2.4/dazzle_filekit/metadata.py +923 -0
  5. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/dazzle_filekit/operations.py +172 -193
  6. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/dazzle_filekit/paths.py +207 -12
  7. dazzle_filekit-0.2.4/dazzle_filekit/platform/windows.py +149 -0
  8. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/dazzle_filekit/utils/__init__.py +2 -2
  9. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/dazzle_filekit/utils/compat.py +42 -63
  10. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/dazzle_filekit/utils/validation.py +79 -17
  11. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/dazzle_filekit.egg-info/PKG-INFO +100 -51
  12. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/dazzle_filekit.egg-info/SOURCES.txt +7 -0
  13. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/dazzle_filekit.egg-info/requires.txt +3 -0
  14. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/pyproject.toml +10 -2
  15. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/setup.py +1 -1
  16. dazzle_filekit-0.2.4/tests/test_ads_and_junction_v024.py +187 -0
  17. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/tests/test_compat.py +19 -4
  18. dazzle_filekit-0.2.4/tests/test_import_stability.py +175 -0
  19. dazzle_filekit-0.2.4/tests/test_metadata_v024_roundtrip.py +368 -0
  20. dazzle_filekit-0.2.4/tests/test_operations_primitives_v024.py +280 -0
  21. dazzle_filekit-0.2.4/tests/test_paths_platform_simulation.py +270 -0
  22. dazzle_filekit-0.2.4/tests/test_paths_v024_enrichments.py +282 -0
  23. dazzle_filekit-0.2.2/README.md +0 -266
  24. dazzle_filekit-0.2.2/dazzle_filekit/platform/windows.py +0 -48
  25. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/LICENSE +0 -0
  26. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/dazzle_filekit/platform/__init__.py +0 -0
  27. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/dazzle_filekit/platform/unix.py +0 -0
  28. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/dazzle_filekit/utils/disk.py +0 -0
  29. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/dazzle_filekit/utils/logger.py +0 -0
  30. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/dazzle_filekit/verification.py +0 -0
  31. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/dazzle_filekit.egg-info/dependency_links.txt +0 -0
  32. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/dazzle_filekit.egg-info/top_level.txt +0 -0
  33. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/setup.cfg +0 -0
  34. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/tests/test_auto_naming.py +0 -0
  35. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/tests/test_disk.py +0 -0
  36. {dazzle_filekit-0.2.2 → dazzle_filekit-0.2.4}/tests/test_smoke.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: dazzle-filekit
3
- Version: 0.2.2
3
+ Version: 0.2.4
4
4
  Summary: Cross-platform file operations toolkit with path handling, verification, and metadata preservation
5
5
  Author: Dustin
6
6
  Author-email: Dustin Darcy <6962246+djdarcy@users.noreply.github.com>
@@ -28,6 +28,7 @@ Requires-Python: >=3.6
28
28
  Description-Content-Type: text/markdown
29
29
  License-File: LICENSE
30
30
  Requires-Dist: pathlib; python_version < "3.4"
31
+ Requires-Dist: pywin32>=305; sys_platform == "win32"
31
32
  Provides-Extra: unctools
32
33
  Requires-Dist: unctools>=0.1.0; extra == "unctools"
33
34
  Provides-Extra: dev
@@ -41,11 +42,13 @@ Dynamic: requires-python
41
42
 
42
43
  # dazzle-filekit
43
44
 
44
- [![PyPI version](https://img.shields.io/pypi/v/dazzle-filekit.svg)](https://pypi.org/project/dazzle-filekit/)
45
- [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
46
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
47
- [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS%20%7C%20BSD-lightgrey.svg)](docs/platform-support.md)
45
+ [![Release Date](https://img.shields.io/github/release-date/DazzleLib/dazzle-filekit?color=green)](https://github.com/DazzleLib/dazzle-filekit/releases)
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)
48
+ [![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
49
+ [![License](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
48
50
  [![GitHub Discussions](https://img.shields.io/github/discussions/DazzleLib/dazzle-filekit)](https://github.com/DazzleLib/dazzle-filekit/discussions)
51
+ [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)](docs/platform-support.md)
49
52
 
50
53
  > **Cross-platform file operations with path handling, verification, and metadata preservation.**
51
54
 
@@ -53,12 +56,17 @@ A Python toolkit for reliable file operations across Windows, Linux, and macOS.
53
56
 
54
57
  ## Features
55
58
 
56
- - **Cross-Platform Paths** - Normalize between Git Bash (`/c/...`), WSL (`/mnt/c/...`), and native Windows/Unix paths
59
+ - **Cross-Platform Paths** - Normalize between Git Bash (`/c/...`), WSL (`/mnt/c/...`), and native Windows/Unix paths via a single canonical `normalize_cross_platform_path(path, *, resolve=False)` entry point
60
+ - **Rich Metadata Preservation** - `dazzle_filekit.metadata` module captures Windows SDDL ACLs (JSON-serializable), NTFS creation time, Unix extended attributes, and attribute flag booleans; restore-on-recovery preserves everything via `pywin32.SetFileTime` for ctime
57
61
  - **File Operations** - Copy, move, and manage files with metadata preservation
62
+ - **Atomic Write Primitives** - `atomic_write_text` / `atomic_write_json` use tmp+rename for crash-safe config and manifest writes
63
+ - **Link-Safe Tree Copy** - `copy_tree_preserving_links` wraps `shutil.copytree(symlinks=True)` with documented intent (never traverses junctions on Windows)
64
+ - **NTFS ADS Detection** - `platform.windows.detect_alternate_streams` enumerates alternate data streams via `FindFirstStreamW`; `has_significant_ads` filters out browser Zone.Identifier noise
65
+ - **Correct Junction Detection** - `is_junction` uses `DeviceIoControl(FSCTL_GET_REPARSE_POINT)` to distinguish real junctions (`IO_REPARSE_TAG_MOUNT_POINT`) from directory symlinks
58
66
  - **File Verification** - Calculate and verify file hashes (MD5, SHA1, SHA256, SHA512)
59
67
  - **Disk Space Checking** - Pre-flight space verification before operations
60
- - **Platform Support** - Windows, Linux, macOS, and BSD with platform-specific optimizations
61
- - **UNC Path Support** - Optional integration with `unctools` for Windows UNC path handling
68
+ - **Platform Support** - Windows, Linux, and macOS with platform-specific optimizations
69
+ - **UNC Path Detection** - Native `is_unc_path` / `get_path_type` helpers; optional [UNCtools](https://github.com/DazzleLib/UNCtools) peer for UNC ↔ drive-letter translation (see [docs/unctools-integration.md](docs/unctools-integration.md))
62
70
 
63
71
  ## Why dazzle-filekit?
64
72
 
@@ -82,11 +90,13 @@ pip install dazzle-filekit
82
90
  ### Optional Dependencies
83
91
 
84
92
  ```bash
85
- # Windows UNC path support
86
- pip install dazzle-filekit[unctools]
93
+ # UNCtools peer install (enables UNC ↔ drive-letter translation
94
+ # via user-side composition; filekit does not import unctools directly).
95
+ # See docs/unctools-integration.md for composition patterns.
96
+ pip install 'dazzle-filekit[unctools]'
87
97
 
88
98
  # Development tools
89
- pip install dazzle-filekit[dev]
99
+ pip install 'dazzle-filekit[dev]'
90
100
  ```
91
101
 
92
102
  ## Quick Start
@@ -139,14 +149,15 @@ if is_unc_path(r"\\server\share"):
139
149
  ```python
140
150
  from dazzle_filekit import copy_file, collect_file_metadata, create_symlink
141
151
 
142
- # Copy file with metadata preservation
143
- success = copy_file("source.txt", "dest.txt", preserve_metadata=True)
152
+ # Copy file with attribute preservation (timestamps, permissions, etc.)
153
+ success = copy_file("source.txt", "dest.txt", preserve_attrs=True)
144
154
 
145
- # Collect file metadata
155
+ # Collect file metadata (v0.2.4: returns SDDL ACLs on Windows,
156
+ # xattrs on Linux/macOS, ctime, and ISO timestamps alongside the raw floats)
146
157
  metadata = collect_file_metadata("file.txt")
147
- print(f"Size: {metadata['size']}, Modified: {metadata['mtime']}")
158
+ print(f"Size: {metadata['size']}, Modified: {metadata['timestamps']['modified_iso']}")
148
159
 
149
- # Create symbolic link (cross-platform)
160
+ # Create symbolic link (cross-platform, with Windows fallbacks)
150
161
  success = create_symlink("/path/to/target", "/path/to/link")
151
162
 
152
163
  # Force replace existing link
@@ -188,51 +199,73 @@ hash_value = calculate_file_hash("file.txt", algorithm="sha256")
188
199
  is_valid = verify_file_hash("file.txt", expected_hash, algorithm="sha256")
189
200
  ```
190
201
 
191
- ## API Reference
202
+ ### Atomic Writes (v0.2.4)
192
203
 
193
- ### Cross-Platform Utilities
204
+ ```python
205
+ from dazzle_filekit import atomic_write_text, atomic_write_json
206
+
207
+ # Atomic text write (tmp + os.replace). Crash mid-write leaves the
208
+ # original file intact; readers see either the old or the new contents.
209
+ atomic_write_text("config.ini", "[section]\nkey=value\n")
210
+
211
+ # Atomic JSON write with sensible defaults. default=str handles
212
+ # datetime, Path, and other non-JSON-native types out of the box.
213
+ atomic_write_json("manifest.json", {
214
+ "version": "1.0",
215
+ "created_at": datetime.datetime.now(),
216
+ "root": Path("/data"),
217
+ })
218
+ ```
194
219
 
195
- - `normalize_cross_platform_path(path)` - Normalize Git Bash/WSL/Windows paths to native format
196
- - `resolve_cross_platform_path(path)` - Normalize and probe alternate platform formats if path not found
197
- - `path_exists_cross_platform(path)` - Check path existence across formats
198
- - `is_windows()` / `is_unix()` - Platform detection
220
+ ### Rich Metadata (v0.2.4)
199
221
 
200
- ### Path Functions
222
+ ```python
223
+ from dazzle_filekit import metadata
201
224
 
202
- - `normalize_path(path)` - Normalize path to canonical form
203
- - `is_same_file(path1, path2)` - Check if paths refer to same file
204
- - `split_drive_letter(path)` - Split drive letter from path (Windows)
205
- - `is_unc_path(path)` - Check if path is UNC format
206
- - `get_relative_path(path, base)` - Get relative path from base
207
- - `find_files(directory, patterns, exclude)` - Find files matching patterns
208
- - `get_path_type(path)` - Detect path type (unc, network, subst, local)
225
+ # Collect rich metadata. On Windows this captures SDDL ACL strings
226
+ # (JSON-serializable), creation time, file attribute flags, and owner.
227
+ # On Linux/macOS it captures extended attributes (xattrs) as base64.
228
+ md = metadata.collect_file_metadata("important.txt")
209
229
 
210
- ### File Operations
230
+ # Save it as JSON alongside the file
231
+ import json
232
+ with open("important.txt.meta.json", "w") as f:
233
+ json.dump(metadata.metadata_to_json(md), f, indent=2)
234
+
235
+ # Later, restore metadata to a copy (including Windows ctime)
236
+ metadata.apply_file_metadata("restored.txt", md)
237
+
238
+ # Check if the richer Windows code path is available
239
+ if metadata.is_win32_available():
240
+ print("pywin32 present -- full SDDL/ctime/ADS support")
241
+ ```
211
242
 
212
- - `copy_file(src, dst, preserve_metadata)` - Copy file with options
213
- - `move_file(src, dst, preserve_metadata)` - Move file with options
214
- - `collect_file_metadata(path)` - Collect file metadata
215
- - `apply_file_metadata(path, metadata)` - Apply metadata to file
216
- - `create_directory_structure(path)` - Create directory tree
217
- - `remove_file(path)` - Remove file safely
218
- - `remove_directory(path, recursive)` - Remove directory
219
- - `create_symlink(target, link, force)` - Create symbolic link with cross-platform support
243
+ ### Link-Safe Tree Copy (v0.2.4)
220
244
 
221
- ### Disk Space Functions
245
+ ```python
246
+ from dazzle_filekit import copy_tree_preserving_links
247
+
248
+ # Copies the tree, preserving symlinks and junctions as links (never
249
+ # traversing them). Safe for copying source trees that may contain
250
+ # self-referential junctions on Windows.
251
+ copy_tree_preserving_links("src_tree", "dst_tree", dirs_exist_ok=True)
252
+ ```
222
253
 
223
- - `get_disk_usage(path)` - Get disk usage statistics (total, used, free)
224
- - `check_disk_space(dest, required, margin)` - Check if space is sufficient
225
- - `calculate_total_size(paths)` - Calculate total size of files/directories
226
- - `ensure_disk_space(dest, sources, margin)` - Verify space for copy operation
254
+ ## API at a glance
227
255
 
228
- ### Verification Functions
256
+ The Quick Start above covers the common 90% of what most users need.
257
+ For the full function-by-function reference, see
258
+ **[docs/api-reference.md](docs/api-reference.md)**.
229
259
 
230
- - `calculate_file_hash(path, algorithm)` - Calculate file hash
231
- - `verify_file_hash(path, expected_hash, algorithm)` - Verify hash
232
- - `calculate_directory_hashes(directory, algorithm)` - Hash all files in directory
233
- - `save_hashes_to_file(hashes, output_file)` / `load_hashes_from_file(hash_file)` - Hash persistence
234
- - `compare_directories(dir1, dir2)` - Compare directory contents
235
- - `verify_copied_files(src_dir, dst_dir)` - Verify copy operation
260
+ | Area | Key entry points |
261
+ |------|------------------|
262
+ | **Paths** | `normalize_cross_platform_path(path, *, resolve=False)` (canonical), `resolve_cross_platform_path`, `path_exists_cross_platform`, `is_wsl()` |
263
+ | **File ops** | `copy_file`, `move_file`, `create_symlink`, `copy_tree_preserving_links`, `atomic_write_text`, `atomic_write_json` |
264
+ | **Metadata** | `dazzle_filekit.metadata` -- `collect_file_metadata`, `apply_file_metadata`, `restore_windows_creation_time`, `compare_metadata`, `is_win32_available` |
265
+ | **Platform (Windows)** | `dazzle_filekit.platform.windows` -- `detect_alternate_streams`, `has_significant_ads`, `is_admin` |
266
+ | **Disk space** | `get_disk_usage`, `check_disk_space`, `calculate_total_size`, `ensure_disk_space` |
267
+ | **Verification** | `calculate_file_hash`, `verify_file_hash`, `verify_files_with_manifest`, `compare_directories` |
268
+ | **UNC detection** | `is_unc_path`, `get_path_type` (compose with UNCtools for translation -- see [docs/unctools-integration.md](docs/unctools-integration.md)) |
236
269
 
237
270
  ## Platform Support
238
271
 
@@ -274,7 +307,11 @@ pip install -e ".[dev]"
274
307
  ### Run Tests
275
308
 
276
309
  ```bash
310
+ # Standard run
277
311
  pytest tests/ -v --cov=dazzle_filekit
312
+
313
+ # Cross-platform cross-check (Windows + WSL Ubuntu from one command)
314
+ ./scripts/run-cross-platform-tests.sh
278
315
  ```
279
316
 
280
317
  ### Code Formatting
@@ -284,6 +321,18 @@ black dazzle_filekit tests
284
321
  flake8 dazzle_filekit tests
285
322
  ```
286
323
 
324
+ ## Documentation
325
+
326
+ - **[docs/api-reference.md](docs/api-reference.md)** -- full function-by-function reference
327
+ - **[docs/api-stability.md](docs/api-stability.md)** -- locked public API surface and known external callers. Changes to symbols listed here require a migration plan.
328
+ - **[docs/platform-support.md](docs/platform-support.md)** -- platform matrix, test counts, and platform-specific feature breakdown
329
+ - **[docs/preservelib-integration.md](docs/preservelib-integration.md)** -- how preservelib composes with filekit and the layering contract
330
+ - **[docs/unctools-integration.md](docs/unctools-integration.md)** -- UNCtools composition patterns (filekit does UNC detection; unctools does UNC translation; user code composes them)
331
+ - **[BREAKING_CHANGES.md](BREAKING_CHANGES.md)** -- forward-looking log of version-specific breaks and the Phase 4+ migration procedure
332
+ - **[CHANGELOG.md](CHANGELOG.md)** -- version history
333
+
334
+ `tests/test_import_stability.py` is the automated canary that enforces `docs/api-stability.md`. If you rename or remove a locked symbol, that test will fail.
335
+
287
336
  ## Contributing
288
337
 
289
338
  Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
@@ -0,0 +1,314 @@
1
+ # dazzle-filekit
2
+
3
+ [![Release Date](https://img.shields.io/github/release-date/DazzleLib/dazzle-filekit?color=green)](https://github.com/DazzleLib/dazzle-filekit/releases)
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)
6
+ [![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
7
+ [![License](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
8
+ [![GitHub Discussions](https://img.shields.io/github/discussions/DazzleLib/dazzle-filekit)](https://github.com/DazzleLib/dazzle-filekit/discussions)
9
+ [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)](docs/platform-support.md)
10
+
11
+ > **Cross-platform file operations with path handling, verification, and metadata preservation.**
12
+
13
+ A Python toolkit for reliable file operations across Windows, Linux, and macOS. Handles path normalization between Git Bash, WSL, and native formats, file verification with multiple hash algorithms, and metadata-preserving copy/move operations.
14
+
15
+ ## Features
16
+
17
+ - **Cross-Platform Paths** - Normalize between Git Bash (`/c/...`), WSL (`/mnt/c/...`), and native Windows/Unix paths via a single canonical `normalize_cross_platform_path(path, *, resolve=False)` entry point
18
+ - **Rich Metadata Preservation** - `dazzle_filekit.metadata` module captures Windows SDDL ACLs (JSON-serializable), NTFS creation time, Unix extended attributes, and attribute flag booleans; restore-on-recovery preserves everything via `pywin32.SetFileTime` for ctime
19
+ - **File Operations** - Copy, move, and manage files with metadata preservation
20
+ - **Atomic Write Primitives** - `atomic_write_text` / `atomic_write_json` use tmp+rename for crash-safe config and manifest writes
21
+ - **Link-Safe Tree Copy** - `copy_tree_preserving_links` wraps `shutil.copytree(symlinks=True)` with documented intent (never traverses junctions on Windows)
22
+ - **NTFS ADS Detection** - `platform.windows.detect_alternate_streams` enumerates alternate data streams via `FindFirstStreamW`; `has_significant_ads` filters out browser Zone.Identifier noise
23
+ - **Correct Junction Detection** - `is_junction` uses `DeviceIoControl(FSCTL_GET_REPARSE_POINT)` to distinguish real junctions (`IO_REPARSE_TAG_MOUNT_POINT`) from directory symlinks
24
+ - **File Verification** - Calculate and verify file hashes (MD5, SHA1, SHA256, SHA512)
25
+ - **Disk Space Checking** - Pre-flight space verification before operations
26
+ - **Platform Support** - Windows, Linux, and macOS with platform-specific optimizations
27
+ - **UNC Path Detection** - Native `is_unc_path` / `get_path_type` helpers; optional [UNCtools](https://github.com/DazzleLib/UNCtools) peer for UNC ↔ drive-letter translation (see [docs/unctools-integration.md](docs/unctools-integration.md))
28
+
29
+ ## Why dazzle-filekit?
30
+
31
+ While Python's standard library (`shutil`, `pathlib`, `os`) provides basic file operations, dazzle-filekit offers:
32
+
33
+ - **Metadata Preservation**: Automatic preservation of timestamps, permissions, and extended attributes across platforms
34
+ - **Hash Verification**: Built-in file verification with multiple hash algorithms (MD5, SHA1, SHA256, SHA512)
35
+ - **Cross-Platform Path Handling**: Unified API for handling Windows UNC paths, network drives, and Unix paths
36
+ - **Batch Operations**: Process entire directory trees with pattern matching and filtering
37
+ - **Safe Operations**: Built-in conflict resolution, unique path generation, and error handling
38
+ - **Directory Comparison**: Compare directory contents and verify file integrity across locations
39
+
40
+ dazzle-filekit was designed for applications requiring reliable file operations with verification, such as backup tools, file synchronization, and data preservation systems (like the [preserve](https://github.com/DazzleTools/preserve) project).
41
+
42
+ ## Installation
43
+
44
+ ```bash
45
+ pip install dazzle-filekit
46
+ ```
47
+
48
+ ### Optional Dependencies
49
+
50
+ ```bash
51
+ # UNCtools peer install (enables UNC ↔ drive-letter translation
52
+ # via user-side composition; filekit does not import unctools directly).
53
+ # See docs/unctools-integration.md for composition patterns.
54
+ pip install 'dazzle-filekit[unctools]'
55
+
56
+ # Development tools
57
+ pip install 'dazzle-filekit[dev]'
58
+ ```
59
+
60
+ ## Quick Start
61
+
62
+ ### Cross-Platform Path Handling
63
+
64
+ ```python
65
+ from dazzle_filekit import (
66
+ normalize_cross_platform_path,
67
+ resolve_cross_platform_path,
68
+ path_exists_cross_platform,
69
+ )
70
+
71
+ # Convert Git Bash style paths to native format
72
+ # On Windows: /c/Users/foo -> C:\Users\foo
73
+ # On Unix: C:\Users\foo -> /c/Users/foo
74
+ path = normalize_cross_platform_path("/c/Users/foo/file.txt")
75
+
76
+ # Also handles WSL paths: /mnt/c/Users/...
77
+ path = normalize_cross_platform_path("/mnt/c/Users/foo/file.txt")
78
+
79
+ # Resolve with probing: if the normalized path doesn't exist,
80
+ # tries alternate platform formats (WSL, MSYS, Windows)
81
+ path = resolve_cross_platform_path("/mnt/c/Users/foo/file.txt")
82
+
83
+ # Check if a cross-platform path exists (uses resolve internally)
84
+ if path_exists_cross_platform("/c/Users/foo/file.txt"):
85
+ print("File exists!")
86
+ ```
87
+
88
+ ### Path Operations
89
+
90
+ ```python
91
+ from dazzle_filekit import normalize_path, find_files, is_unc_path
92
+
93
+ # Normalize paths (returns Path object)
94
+ path = normalize_path("/some/path/../file.txt")
95
+ print(path) # PosixPath('/some/file.txt') or WindowsPath('C:/some/file.txt')
96
+
97
+ # Find files with patterns (returns list of path strings)
98
+ files = find_files("/directory", patterns=["*.py", "*.txt"])
99
+
100
+ # Check UNC paths
101
+ if is_unc_path(r"\\server\share"):
102
+ print("This is a UNC path")
103
+ ```
104
+
105
+ ### File Operations
106
+
107
+ ```python
108
+ from dazzle_filekit import copy_file, collect_file_metadata, create_symlink
109
+
110
+ # Copy file with attribute preservation (timestamps, permissions, etc.)
111
+ success = copy_file("source.txt", "dest.txt", preserve_attrs=True)
112
+
113
+ # Collect file metadata (v0.2.4: returns SDDL ACLs on Windows,
114
+ # xattrs on Linux/macOS, ctime, and ISO timestamps alongside the raw floats)
115
+ metadata = collect_file_metadata("file.txt")
116
+ print(f"Size: {metadata['size']}, Modified: {metadata['timestamps']['modified_iso']}")
117
+
118
+ # Create symbolic link (cross-platform, with Windows fallbacks)
119
+ success = create_symlink("/path/to/target", "/path/to/link")
120
+
121
+ # Force replace existing link
122
+ success = create_symlink("/new/target", "/path/to/link", force=True)
123
+ ```
124
+
125
+ ### Disk Space Checking
126
+
127
+ ```python
128
+ from dazzle_filekit import get_disk_usage, check_disk_space, ensure_disk_space
129
+
130
+ # Get disk usage statistics
131
+ usage = get_disk_usage("/path/to/check")
132
+ print(f"Total: {usage.total}, Free: {usage.free}, Used: {usage.used_percent:.1f}%")
133
+
134
+ # Check if space is available for an operation
135
+ has_space, required, available, message = check_disk_space(
136
+ "/destination",
137
+ required_bytes=1_000_000_000, # 1GB
138
+ safety_margin=0.1 # 10% extra margin
139
+ )
140
+
141
+ # Check space for a list of source files
142
+ has_space, message = ensure_disk_space(
143
+ dest_path="/destination",
144
+ source_paths=["/path/to/file1.zip", "/path/to/dir/"]
145
+ )
146
+ ```
147
+
148
+ ### File Verification
149
+
150
+ ```python
151
+ from dazzle_filekit import calculate_file_hash, verify_file_hash
152
+
153
+ # Calculate hash
154
+ hash_value = calculate_file_hash("file.txt", algorithm="sha256")
155
+
156
+ # Verify hash
157
+ is_valid = verify_file_hash("file.txt", expected_hash, algorithm="sha256")
158
+ ```
159
+
160
+ ### Atomic Writes (v0.2.4)
161
+
162
+ ```python
163
+ from dazzle_filekit import atomic_write_text, atomic_write_json
164
+
165
+ # Atomic text write (tmp + os.replace). Crash mid-write leaves the
166
+ # original file intact; readers see either the old or the new contents.
167
+ atomic_write_text("config.ini", "[section]\nkey=value\n")
168
+
169
+ # Atomic JSON write with sensible defaults. default=str handles
170
+ # datetime, Path, and other non-JSON-native types out of the box.
171
+ atomic_write_json("manifest.json", {
172
+ "version": "1.0",
173
+ "created_at": datetime.datetime.now(),
174
+ "root": Path("/data"),
175
+ })
176
+ ```
177
+
178
+ ### Rich Metadata (v0.2.4)
179
+
180
+ ```python
181
+ from dazzle_filekit import metadata
182
+
183
+ # Collect rich metadata. On Windows this captures SDDL ACL strings
184
+ # (JSON-serializable), creation time, file attribute flags, and owner.
185
+ # On Linux/macOS it captures extended attributes (xattrs) as base64.
186
+ md = metadata.collect_file_metadata("important.txt")
187
+
188
+ # Save it as JSON alongside the file
189
+ import json
190
+ with open("important.txt.meta.json", "w") as f:
191
+ json.dump(metadata.metadata_to_json(md), f, indent=2)
192
+
193
+ # Later, restore metadata to a copy (including Windows ctime)
194
+ metadata.apply_file_metadata("restored.txt", md)
195
+
196
+ # Check if the richer Windows code path is available
197
+ if metadata.is_win32_available():
198
+ print("pywin32 present -- full SDDL/ctime/ADS support")
199
+ ```
200
+
201
+ ### Link-Safe Tree Copy (v0.2.4)
202
+
203
+ ```python
204
+ from dazzle_filekit import copy_tree_preserving_links
205
+
206
+ # Copies the tree, preserving symlinks and junctions as links (never
207
+ # traversing them). Safe for copying source trees that may contain
208
+ # self-referential junctions on Windows.
209
+ copy_tree_preserving_links("src_tree", "dst_tree", dirs_exist_ok=True)
210
+ ```
211
+
212
+ ## API at a glance
213
+
214
+ The Quick Start above covers the common 90% of what most users need.
215
+ For the full function-by-function reference, see
216
+ **[docs/api-reference.md](docs/api-reference.md)**.
217
+
218
+ | Area | Key entry points |
219
+ |------|------------------|
220
+ | **Paths** | `normalize_cross_platform_path(path, *, resolve=False)` (canonical), `resolve_cross_platform_path`, `path_exists_cross_platform`, `is_wsl()` |
221
+ | **File ops** | `copy_file`, `move_file`, `create_symlink`, `copy_tree_preserving_links`, `atomic_write_text`, `atomic_write_json` |
222
+ | **Metadata** | `dazzle_filekit.metadata` -- `collect_file_metadata`, `apply_file_metadata`, `restore_windows_creation_time`, `compare_metadata`, `is_win32_available` |
223
+ | **Platform (Windows)** | `dazzle_filekit.platform.windows` -- `detect_alternate_streams`, `has_significant_ads`, `is_admin` |
224
+ | **Disk space** | `get_disk_usage`, `check_disk_space`, `calculate_total_size`, `ensure_disk_space` |
225
+ | **Verification** | `calculate_file_hash`, `verify_file_hash`, `verify_files_with_manifest`, `compare_directories` |
226
+ | **UNC detection** | `is_unc_path`, `get_path_type` (compose with UNCtools for translation -- see [docs/unctools-integration.md](docs/unctools-integration.md)) |
227
+
228
+ ## Platform Support
229
+
230
+ See [docs/platform-support.md](docs/platform-support.md) for the full platform support matrix and platform-specific features.
231
+
232
+ | Platform | Status |
233
+ |----------|--------|
234
+ | Windows 10/11 | Tested |
235
+ | Linux | Tested |
236
+ | WSL / WSL2 | Tested |
237
+ | macOS | Expected to work |
238
+ | BSD | Expected to work |
239
+
240
+ ## Configuration
241
+
242
+ ### Logging
243
+
244
+ ```python
245
+ from dazzle_filekit import configure_logging, enable_verbose_logging
246
+ import logging
247
+
248
+ # Configure logging level
249
+ configure_logging(level=logging.DEBUG, log_file="dazzle-filekit.log")
250
+
251
+ # Or enable verbose logging
252
+ enable_verbose_logging()
253
+ ```
254
+
255
+ ## Development
256
+
257
+ ### Setup Development Environment
258
+
259
+ ```bash
260
+ git clone https://github.com/DazzleLib/dazzle-filekit.git
261
+ cd dazzle-filekit
262
+ pip install -e ".[dev]"
263
+ ```
264
+
265
+ ### Run Tests
266
+
267
+ ```bash
268
+ # Standard run
269
+ pytest tests/ -v --cov=dazzle_filekit
270
+
271
+ # Cross-platform cross-check (Windows + WSL Ubuntu from one command)
272
+ ./scripts/run-cross-platform-tests.sh
273
+ ```
274
+
275
+ ### Code Formatting
276
+
277
+ ```bash
278
+ black dazzle_filekit tests
279
+ flake8 dazzle_filekit tests
280
+ ```
281
+
282
+ ## Documentation
283
+
284
+ - **[docs/api-reference.md](docs/api-reference.md)** -- full function-by-function reference
285
+ - **[docs/api-stability.md](docs/api-stability.md)** -- locked public API surface and known external callers. Changes to symbols listed here require a migration plan.
286
+ - **[docs/platform-support.md](docs/platform-support.md)** -- platform matrix, test counts, and platform-specific feature breakdown
287
+ - **[docs/preservelib-integration.md](docs/preservelib-integration.md)** -- how preservelib composes with filekit and the layering contract
288
+ - **[docs/unctools-integration.md](docs/unctools-integration.md)** -- UNCtools composition patterns (filekit does UNC detection; unctools does UNC translation; user code composes them)
289
+ - **[BREAKING_CHANGES.md](BREAKING_CHANGES.md)** -- forward-looking log of version-specific breaks and the Phase 4+ migration procedure
290
+ - **[CHANGELOG.md](CHANGELOG.md)** -- version history
291
+
292
+ `tests/test_import_stability.py` is the automated canary that enforces `docs/api-stability.md`. If you rename or remove a locked symbol, that test will fail.
293
+
294
+ ## Contributing
295
+
296
+ Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
297
+
298
+ Like the project?
299
+
300
+ [!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/djdarcy)
301
+
302
+ ## License
303
+
304
+ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
305
+
306
+ ## Part of DazzleLib
307
+
308
+ dazzle-filekit is part of the [DazzleLib](https://github.com/DazzleLib) ecosystem of Python file manipulation tools.
309
+
310
+ ### Related Projects
311
+
312
+ - [UNCtools](https://github.com/DazzleLib/UNCtools) - Windows UNC path utilities
313
+ - [preserve](https://github.com/DazzleTools/preserve) - File preservation with manifest tracking and restoration
314
+ - [dazzle-tree-lib](https://github.com/DazzleLib/dazzle-tree-lib) - Tree structure utilities
@@ -25,6 +25,7 @@ if not logger.handlers:
25
25
  # Import core functionality
26
26
  from .paths import (
27
27
  normalize_path,
28
+ normalize_path_no_resolve,
28
29
  is_same_file,
29
30
  split_drive_letter,
30
31
  is_unc_path,
@@ -43,7 +44,8 @@ from .utils.compat import (
43
44
  resolve_cross_platform_path,
44
45
  path_exists_cross_platform,
45
46
  is_windows,
46
- is_unix
47
+ is_unix,
48
+ is_wsl,
47
49
  )
48
50
 
49
51
  from .utils.disk import (
@@ -65,7 +67,11 @@ from .operations import (
65
67
  create_directory_structure,
66
68
  remove_file,
67
69
  remove_directory,
68
- create_symlink
70
+ create_symlink,
71
+ # v0.2.4 primitives
72
+ atomic_write_text,
73
+ atomic_write_json,
74
+ copy_tree_preserving_links,
69
75
  )
70
76
 
71
77
  from .verification import (
@@ -79,7 +85,19 @@ from .verification import (
79
85
  verify_copied_files
80
86
  )
81
87
 
82
- __version__ = '0.2.1'
88
+ # Expose dazzle_filekit.metadata as a public submodule so callers can do:
89
+ # from dazzle_filekit import metadata
90
+ # md = metadata.collect_file_metadata(path)
91
+ # alongside the top-level convenience imports from .operations above.
92
+ from . import metadata # noqa: F401
93
+ from .metadata import (
94
+ is_win32_available,
95
+ restore_windows_creation_time,
96
+ compare_metadata,
97
+ metadata_to_json,
98
+ )
99
+
100
+ __version__ = '0.2.4'
83
101
 
84
102
  def configure_logging(level=logging.INFO, log_file=None):
85
103
  """
@@ -147,6 +165,7 @@ __all__ = [
147
165
 
148
166
  # Path functions
149
167
  'normalize_path',
168
+ 'normalize_path_no_resolve',
150
169
  'is_same_file',
151
170
  'split_drive_letter',
152
171
  'is_unc_path',
@@ -165,6 +184,7 @@ __all__ = [
165
184
  'path_exists_cross_platform',
166
185
  'is_windows',
167
186
  'is_unix',
187
+ 'is_wsl',
168
188
 
169
189
  # Disk space utilities
170
190
  'DiskUsage',
@@ -185,6 +205,18 @@ __all__ = [
185
205
  'remove_file',
186
206
  'remove_directory',
187
207
  'create_symlink',
208
+
209
+ # v0.2.4 primitives
210
+ 'atomic_write_text',
211
+ 'atomic_write_json',
212
+ 'copy_tree_preserving_links',
213
+
214
+ # Rich metadata module (v0.2.4)
215
+ 'metadata',
216
+ 'is_win32_available',
217
+ 'restore_windows_creation_time',
218
+ 'compare_metadata',
219
+ 'metadata_to_json',
188
220
 
189
221
  # Verification functions
190
222
  'calculate_file_hash',