dazzle-filekit 0.2.3__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.
- {dazzle_filekit-0.2.3 → dazzle_filekit-0.2.4}/PKG-INFO +100 -51
- dazzle_filekit-0.2.4/README.md +314 -0
- {dazzle_filekit-0.2.3 → dazzle_filekit-0.2.4}/dazzle_filekit/__init__.py +33 -3
- dazzle_filekit-0.2.4/dazzle_filekit/metadata.py +923 -0
- {dazzle_filekit-0.2.3 → dazzle_filekit-0.2.4}/dazzle_filekit/operations.py +172 -193
- {dazzle_filekit-0.2.3 → dazzle_filekit-0.2.4}/dazzle_filekit/paths.py +189 -55
- dazzle_filekit-0.2.4/dazzle_filekit/platform/windows.py +149 -0
- {dazzle_filekit-0.2.3 → dazzle_filekit-0.2.4}/dazzle_filekit/utils/__init__.py +2 -2
- {dazzle_filekit-0.2.3 → dazzle_filekit-0.2.4}/dazzle_filekit/utils/compat.py +42 -63
- {dazzle_filekit-0.2.3 → dazzle_filekit-0.2.4}/dazzle_filekit/utils/validation.py +79 -17
- {dazzle_filekit-0.2.3 → dazzle_filekit-0.2.4}/dazzle_filekit.egg-info/PKG-INFO +100 -51
- {dazzle_filekit-0.2.3 → dazzle_filekit-0.2.4}/dazzle_filekit.egg-info/SOURCES.txt +7 -0
- {dazzle_filekit-0.2.3 → dazzle_filekit-0.2.4}/dazzle_filekit.egg-info/requires.txt +3 -0
- {dazzle_filekit-0.2.3 → dazzle_filekit-0.2.4}/pyproject.toml +10 -2
- {dazzle_filekit-0.2.3 → dazzle_filekit-0.2.4}/setup.py +1 -1
- dazzle_filekit-0.2.4/tests/test_ads_and_junction_v024.py +187 -0
- {dazzle_filekit-0.2.3 → dazzle_filekit-0.2.4}/tests/test_compat.py +19 -4
- dazzle_filekit-0.2.4/tests/test_import_stability.py +175 -0
- dazzle_filekit-0.2.4/tests/test_metadata_v024_roundtrip.py +368 -0
- dazzle_filekit-0.2.4/tests/test_operations_primitives_v024.py +280 -0
- dazzle_filekit-0.2.4/tests/test_paths_platform_simulation.py +270 -0
- dazzle_filekit-0.2.4/tests/test_paths_v024_enrichments.py +282 -0
- dazzle_filekit-0.2.3/README.md +0 -266
- dazzle_filekit-0.2.3/dazzle_filekit/platform/windows.py +0 -48
- {dazzle_filekit-0.2.3 → dazzle_filekit-0.2.4}/LICENSE +0 -0
- {dazzle_filekit-0.2.3 → dazzle_filekit-0.2.4}/dazzle_filekit/platform/__init__.py +0 -0
- {dazzle_filekit-0.2.3 → dazzle_filekit-0.2.4}/dazzle_filekit/platform/unix.py +0 -0
- {dazzle_filekit-0.2.3 → dazzle_filekit-0.2.4}/dazzle_filekit/utils/disk.py +0 -0
- {dazzle_filekit-0.2.3 → dazzle_filekit-0.2.4}/dazzle_filekit/utils/logger.py +0 -0
- {dazzle_filekit-0.2.3 → dazzle_filekit-0.2.4}/dazzle_filekit/verification.py +0 -0
- {dazzle_filekit-0.2.3 → dazzle_filekit-0.2.4}/dazzle_filekit.egg-info/dependency_links.txt +0 -0
- {dazzle_filekit-0.2.3 → dazzle_filekit-0.2.4}/dazzle_filekit.egg-info/top_level.txt +0 -0
- {dazzle_filekit-0.2.3 → dazzle_filekit-0.2.4}/setup.cfg +0 -0
- {dazzle_filekit-0.2.3 → dazzle_filekit-0.2.4}/tests/test_auto_naming.py +0 -0
- {dazzle_filekit-0.2.3 → dazzle_filekit-0.2.4}/tests/test_disk.py +0 -0
- {dazzle_filekit-0.2.3 → 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.
|
|
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
|
-
[](https://github.com/DazzleLib/dazzle-filekit/releases)
|
|
46
|
+
[](https://pypi.org/project/dazzle-filekit/)
|
|
47
|
+
[](https://pepy.tech/projects/dazzle-filekit)
|
|
48
|
+
[](https://www.python.org/downloads/)
|
|
49
|
+
[](https://opensource.org/licenses/MIT)
|
|
48
50
|
[](https://github.com/DazzleLib/dazzle-filekit/discussions)
|
|
51
|
+
[](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,
|
|
61
|
-
- **UNC Path
|
|
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
|
-
#
|
|
86
|
-
|
|
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
|
|
143
|
-
success = copy_file("source.txt", "dest.txt",
|
|
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['
|
|
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
|
-
|
|
202
|
+
### Atomic Writes (v0.2.4)
|
|
192
203
|
|
|
193
|
-
|
|
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
|
-
|
|
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
|
-
|
|
222
|
+
```python
|
|
223
|
+
from dazzle_filekit import metadata
|
|
201
224
|
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
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
|
-
|
|
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
|
-
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
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
|
+
[](https://github.com/DazzleLib/dazzle-filekit/releases)
|
|
4
|
+
[](https://pypi.org/project/dazzle-filekit/)
|
|
5
|
+
[](https://pepy.tech/projects/dazzle-filekit)
|
|
6
|
+
[](https://www.python.org/downloads/)
|
|
7
|
+
[](https://opensource.org/licenses/MIT)
|
|
8
|
+
[](https://github.com/DazzleLib/dazzle-filekit/discussions)
|
|
9
|
+
[](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
|
+
[](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
|
|
@@ -44,7 +44,8 @@ from .utils.compat import (
|
|
|
44
44
|
resolve_cross_platform_path,
|
|
45
45
|
path_exists_cross_platform,
|
|
46
46
|
is_windows,
|
|
47
|
-
is_unix
|
|
47
|
+
is_unix,
|
|
48
|
+
is_wsl,
|
|
48
49
|
)
|
|
49
50
|
|
|
50
51
|
from .utils.disk import (
|
|
@@ -66,7 +67,11 @@ from .operations import (
|
|
|
66
67
|
create_directory_structure,
|
|
67
68
|
remove_file,
|
|
68
69
|
remove_directory,
|
|
69
|
-
create_symlink
|
|
70
|
+
create_symlink,
|
|
71
|
+
# v0.2.4 primitives
|
|
72
|
+
atomic_write_text,
|
|
73
|
+
atomic_write_json,
|
|
74
|
+
copy_tree_preserving_links,
|
|
70
75
|
)
|
|
71
76
|
|
|
72
77
|
from .verification import (
|
|
@@ -80,7 +85,19 @@ from .verification import (
|
|
|
80
85
|
verify_copied_files
|
|
81
86
|
)
|
|
82
87
|
|
|
83
|
-
|
|
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'
|
|
84
101
|
|
|
85
102
|
def configure_logging(level=logging.INFO, log_file=None):
|
|
86
103
|
"""
|
|
@@ -167,6 +184,7 @@ __all__ = [
|
|
|
167
184
|
'path_exists_cross_platform',
|
|
168
185
|
'is_windows',
|
|
169
186
|
'is_unix',
|
|
187
|
+
'is_wsl',
|
|
170
188
|
|
|
171
189
|
# Disk space utilities
|
|
172
190
|
'DiskUsage',
|
|
@@ -187,6 +205,18 @@ __all__ = [
|
|
|
187
205
|
'remove_file',
|
|
188
206
|
'remove_directory',
|
|
189
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',
|
|
190
220
|
|
|
191
221
|
# Verification functions
|
|
192
222
|
'calculate_file_hash',
|