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 it
from unctools import is_unc_path, convert_to_local

src_root = r"\\server\share\project"
if is_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 on
from dazzletreelib.sync import traverse_tree, FileSystemAdapter, FileSystemNode

files = [node.path for node in traverse_tree(FileSystemNode(src_root), FileSystemAdapter())
         if node.is_leaf()]

# L1 -- dazzle-filekit: do each operation correctly, metadata and all
from dazzle_filekit import copy_file, calculate_file_hash, collect_file_metadata

for src in files:
    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 payloads
from dazzle_lib import FileMetadataDict

snapshot: 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 🛠️