Metadata-Version: 2.4
Name: dazzlesum
Version: 1.5.1
Summary: A cross-platform file checksum utility with DOS compatibility and advanced verification features
Author-email: Dustin Darcy <6962246+djdarcy@users.noreply.github.com>
License: GPL-3.0
Project-URL: Homepage, https://github.com/DazzleTools/dazzlesum
Project-URL: Bug Reports, https://github.com/DazzleTools/dazzlesum/issues
Project-URL: Source, https://github.com/DazzleTools/dazzlesum
Project-URL: Documentation, https://github.com/DazzleTools/dazzlesum#readme
Keywords: checksum,hash,verification,sha256,cross-platform,dos-compatible
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Archiving
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dazzle-lib>=0.6.7
Requires-Dist: dazzle-filekit>=0.3.2
Provides-Extra: windows
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# Dazzlesum

[![PyPI](https://img.shields.io/pypi/v/dazzlesum?color=green)](https://pypi.org/project/dazzlesum/)
[![Release Date](https://img.shields.io/github/release-date/DazzleTools/dazzlesum?color=green)](https://github.com/DazzleTools/dazzlesum/releases)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/dazzlesum?period=total&units=international_system&left_color=black&right_color=green&left_text=downloads)](https://pypistats.org/packages/dazzlesum)
[![CI](https://github.com/DazzleTools/dazzlesum/actions/workflows/python.yml/badge.svg)](https://github.com/DazzleTools/dazzlesum/actions)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: GPL v3](https://img.shields.io/badge/license-GPL%20v3-green.svg)](https://www.gnu.org/licenses/gpl-3.0.html)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS%20%7C%20BSD-lightgrey.svg)](docs/platforms.md)

Dazzlesum is a handy checksum tool designed for data integrity verification across different machines and operating systems. It generates folder-specific checksum files (`.shasum`) that enable verification of file collections, with special attention to DOS shell compatibility and cross-platform consistency.

## Features

- **Multiple Hash Algorithms**: SHA256 (default), SHA512, SHA1, MD5 with consistent cross-platform behavior
- **Cross-Platform Support**: Seamlessly handle checksums between Windows, macOS, Linux, and BSD
- **DOS Compatibility**: ASCII-only output that works perfectly in Windows Command Prompt
- **In-Process Hashing Engine**: Python hashlib (OpenSSL-backed) as the primary engine -- no per-file subprocess overhead; native system tools (certutil, shasum, fsum) remain as fallback for algorithms hashlib lacks
- **Flexible Generation Modes**: Individual `.shasum` files per directory, monolithic files, or both simultaneously
- **Advanced Verification**: Problems-only output shows only failed, missing, or extra files by default
- **Management Operations**: Backup, remove, restore, and list `.shasum` files with comprehensive metadata
- **Enhanced Logging**: 11-level verbosity system (-6 to +4) with granular output control and smart filtering
- **Advanced Exit Codes**: 7 different exit codes based on aggregate verification results for precise automation
- **Squelch System**: Filter specific message types (SUCCESS, NO_SHASUM) for customized output
- **Context-Aware Operations**: Auto-detects whether to create or verify based on directory contents
- **Shadow Directory Support**: Keep source directories clean by storing checksum files in parallel shadow structure

## Use Cases

### 🔧 Data Integrity Verification

Maintain consistent checksum verification across different operating systems. Generate checksums on your Windows machine and verify them on your Linux environment without losing any data integrity checks.

### ⚙️ System Administration

Simplify management of complex directory structures and checksum file collections. Document and reproduce checksum configurations for backup or disaster recovery scenarios.

### 📁 Content Organization

Create organizational structures using checksum verification, then export and share these verification systems with others. Perfect for media libraries (similar to SFVs), project references, or any scenario where data integrity needs to be maintained across multiple locations.

### 🌐 Network Path Management

Automatically handle different representations of network paths across systems while maintaining all checksum metadata and verification capabilities.

## Installation

### Prerequisites

- Python 3.9 or higher
- Operating System: Windows, macOS, Linux, BSD
- Dependencies: `dazzle-lib` and `dazzle-filekit`, installed automatically by pip. UNC-aware path handling comes through filekit, which is backed by [`unctools`](https://github.com/djdarcy/UNCtools)
- The standalone `dazzlesum.py` has no dependencies at all -- see [Standalone](#standalone-no-install) below

### Install from PyPI

```bash
pip install dazzlesum
```

### Manual Installation

```bash
git clone https://github.com/DazzleTools/dazzlesum.git
cd dazzlesum
pip install -e .
```

On Windows:
```cmd
pip install -e ".[windows]"
```

Other potential dependencies down the line:
```bash
pip install -e ".[dev,test,docs]"
```

### Standalone (no install)

`dazzlesum.py` is a single self-contained file with no dependencies beyond the Python standard library. Copy it anywhere and run it directly:

```bash
python dazzlesum.py --help
```

## Quick Start

### Generate checksums (using new subcommand syntax)

Every command takes an optional directory argument. Leave it off to work on the current directory, or name any folder -- local, relative, or a network share:

```bash
# Generate checksums for current directory
dazzlesum create

# Generate checksums recursively
dazzlesum create -r

# ...or point it anywhere else
dazzlesum create -r \\server\share\backups

# Create monolithic checksum file
dazzlesum create -r --mode monolithic

# Generate with verbose output (11 levels available: -6 to +4)
dazzlesum create -r -vv

# Silent mode for automation
dazzlesum verify -r -qqqqqq

# Problems-only with custom squelch filters
dazzlesum verify -r --squelch=SUCCESS,NO_SHASUM

# Keep source directories clean with shadow directory
dazzlesum create -r --shadow-dir ./checksums

# Generate monolithic checksum in shadow directory
dazzlesum create -r --mode monolithic --shadow-dir ./checksums
```

### Verify checksums

```bash
# Verify existing checksums
dazzlesum verify -r

# Verify with detailed output
dazzlesum verify -r -v

# Show all verification results
dazzlesum verify -r --show-all-verifications

# Verify checksums stored in shadow directory
dazzlesum verify -r --shadow-dir ./checksums
```

### Update checksums

```bash
# Update existing checksums for changed files
dazzlesum update -r

# Update only specific file types
dazzlesum update -r --include "*.txt,*.doc"
```

### Manage checksum files

```bash
# Backup all .shasum files
dazzlesum manage -r backup --backup-dir ./checksum-backup

# List all .shasum files with details
dazzlesum manage -r list

# Remove all .shasum files (with confirmation)
dazzlesum manage -r remove

# Restore from backup
dazzlesum manage -r restore --backup-dir ./checksum-backup
```

### Get help

```bash
# General help
dazzlesum --help

# Help for specific commands
dazzlesum create --help
dazzlesum verify --help

# Detailed help topics
dazzlesum mode        # Help for --mode parameter
dazzlesum examples    # Comprehensive usage examples
dazzlesum shadow      # Shadow directory help
```

## Documentation

- **[Installation Guide](docs/installation.md)** - Detailed installation instructions for all platforms
- **[Usage Examples](docs/usage-examples.md)** - Practical examples for common use cases
- **[Shadow Directory Guide](docs/shadow-directory.md)** - Complete guide to shadow directory operations
- **[Command Reference](docs/command-reference.md)** - Complete command-line reference
- **[File Formats](docs/file-formats.md)** - Details about `.shasum` file formats and compatibility

## Platform Support

Windows, Linux, macOS, and BSD. Hashing runs in-process via Python `hashlib` on every platform; native tools are a fallback for algorithms it lacks. Text files are line-ending normalized before hashing, so manifests generated on one platform verify on another. Junctions and symlinks are not followed by default.

See **[docs/platforms.md](docs/platforms.md)** for the verification matrix, per-platform behavior, and the reasoning behind the hashing engine order.

## Requirements

- **Python**: 3.9 or higher
- **Operating System**: Windows, macOS, Linux, BSD -- see [docs/platforms.md](docs/platforms.md)
- **Dependencies**: `dazzle-lib` and `dazzle-filekit` for the pip package (installed automatically); none at all for the standalone `dazzlesum.py`

## Future Possible Features
- **Compression**: Archive support for checksum collections
- **Remote Storage**: Cloud backup integration? (maybe)

## Contributing

Contributions are welcome! Issues, suggestions, and bug reports are all appreciated. Please open an [issue](https://github.com/DazzleTools/dazzlesum/issues) if you find something that can be improved. Or: 

1. Fork this repository and clone a fork.
2. Make changes on a new branch (e.g., `feature/new_thing`).
3. Submit a pull request describing your changes.

Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

Like the project?

[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/djdarcy)

## License

dazzlesum, Copyright (C) 2026 Dustin Darcy

Licensed under the [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.html) (GPL-3.0) -- see [LICENSE](LICENSE)

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.

## Support

- **Issues**: [GitHub Issues](https://github.com/DazzleTools/dazzlesum/issues)
- **Discussions**: [GitHub Discussions](https://github.com/DazzleTools/dazzlesum/discussions)
- **Documentation**: Check the [docs/](docs/) folder for additional guides

---

Made with ️☕. Designed for reliable, consistent data integrity verification across all platforms.
