Foundation Libraries for the Dazzle Ecosystem

High-quality, reusable Python libraries that power DazzleTools, DazzleML, and DazzleNodes.

DazzleLib is a collection of foundational Python libraries designed to solve common development challenges with cross-platform compatibility, robust error handling, and minimal dependencies. Built on principles of composability and clarity, these libraries are the building blocks powering the entire Dazzle ecosystem.

Read our design philosophy →

DazzleLib's libraries form a layered stack with one rule above all: every capability has exactly one home, and dependencies only point down. The full architecture contract lives in STACK-MAP.md (frozen v1.0, 2026-06-11).

graph TD
subgraph TOOLS["DazzleTools -- CLI tools (consumers)"]
preserve_cli["preserve"]
dzlink_cli["dazzlelink"]
other["safedel · csb · ghtraf · ..."]
end
subgraph LIBS["DazzleLib -- libraries"]
preservelib["L3 dazzle-preservelib"]
dzlinklib["L2 dazzle-linklib"]
filekit["L1 dazzle-filekit"]
unctools["L0 dazzle-unctools"]
treelib["⊥ dazzle-treelib"]
bedrock["B dazzle-lib"]
end
preserve_cli --> preservelib
dzlink_cli --> dzlinklib
other --> preservelib
other --> filekit
preservelib --> filekit
preservelib -. "optional backend" .-> dzlinklib
dzlinklib --> filekit
dzlinklib --> unctools
unctools --> bedrock
filekit --> bedrock
dzlinklib --> bedrock
preservelib --> bedrock
treelib -. optional .-> bedrock

The rules in brief: one home per capability · dependencies point down (also the MIT/GPL license guard) · sibling imports are real dependencies (extras need hard, named errors) · libraries live here, CLI tools live in DazzleTools · uniform dazzle-* naming on all three axes (dist / import / repo) · migration shims are temporary, noisy, tracked, terminal · names must teach the layer model.

pip install dazzle-lib

The bedrock: shared Protocols, TypedDict payload schemas, and the exception root

Structural contracts every stack library builds on -- Viewable/Serializable protocols, cross-layer payload shapes, one catchable DazzleError root. Types only, stdlib only, behavior banned by charter.

Full documentation → | Repository →

pip install dazzle-filekit

Cross-platform file operations with verification and metadata preservation

File operations (copy, move, verify) with hash calculation, metadata preservation, and cross-platform path handling including Windows UNC paths.

Full documentation → | Repository →

pip install dazzletreelib

Tree structure utilities for hierarchical data

Generic tree data structures with traversal algorithms (DFS, BFS), visualization tools, and path-based operations.

Full documentation → | Repository →

pip install unctools

Windows UNC path handling and network drive utilities

Parse UNC paths, detect network drives, convert between drive letters and UNC paths, and handle long path names (>260 characters). Cross-platform safe with graceful no-ops on Unix systems.

Full documentation → | Repository →

One task, climbing the stack: verify-and-copy a project folder off a network share -- each layer is the basis for the next.

# L0 -- dazzle-unctools: settle the path's IDENTITY before touching itfromunctoolsimportis_unc_path, convert_to_localsrc_root=r"\\server\share\project"ifis_unc_path(src_root):
src_root=convert_to_local(src_root) # mapped drive letter, if one exists# ⊥ -- dazzle-tree-lib: traverse that root to find what to operate onfromdazzletreelib.syncimporttraverse_tree, FileSystemAdapter, FileSystemNodefiles= [node.pathfornodeintraverse_tree(FileSystemNode(src_root), FileSystemAdapter())
ifnode.is_leaf()]
# L1 -- dazzle-filekit: do each operation correctly, metadata and allfromdazzle_filekitimportcopy_file, calculate_file_hash, collect_file_metadataforsrcinfiles:
copy_file(src, f"D:/backup/{src.name}", preserve_attrs=True)
hashes=calculate_file_hash(src, algorithms=["sha256"]) # {"sha256": "..."}# B -- dazzle-lib: results travel as TYPED, serializable payloadsfromdazzle_libimportFileMetadataDictsnapshot: FileMetadataDict=collect_file_metadata(files[0]) # same shape, now contractual# L2 (dazzle-linklib) will serialize links as portable data over these primitives;# L3 (dazzle-preservelib) will wrap the whole flow in a manifest with verification.

Org-level documents live here; per-library documentation lives in each repository's own docs/ (linked from the sections above), so it stays maintained alongside the code.

• Architecture Contract (STACK-MAP) - The frozen layer model: one home per capability, dependencies point down
• Design Philosophy - Principles and architectural decisions
• Library Roadmap - Current status and planned libraries

DazzleLib powers these projects in the Dazzle ecosystem:

DazzleTools: preserve, dazzlelink, relinker (future) DazzleML: File organization and training data management DazzleNodes: ComfyUI custom nodes file operations

Contributions are welcome! Each library has its own repository with contribution guidelines.

General Process:

1. Fork the library repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass (pytest)
5. Submit a pull request

Read full contributing guidelines →

Learn about supporting DazzleLib →

If DazzleLib saves you time, consider sponsoring on GitHub or buying us a coffee

DazzleLib is one of five organizations in the Dazzle ecosystem:

• DazzleProj - Ecosystem coordination
• DazzleLib - Foundation libraries ← You are here
• DazzleTools - Command-line tools
• DazzleNodes - ComfyUI custom nodes
• DazzleML - AI development tools

All DazzleLib libraries are released under the MIT License for maximum compatibility with both open source and commercial projects.

See individual library repositories for specific license files.

• Issues: Use repository-specific issue trackers
• Discussions: GitHub Discussions
• Sponsorship: GitHub Sponsors
• Website: DazzleProj.com(coming soon)

Build better tools with DazzleLib 🛠️