Metadata-Version: 2.4
Name: dazzlesum
Version: 1.4.4
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.7
Classifier: Programming Language :: Python :: 3.8
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: Topic :: System :: Archiving
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: windows
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; python_version >= "3.8" and extra == "dev"
Requires-Dist: black==23.3.0; python_version == "3.7" and extra == "dev"
Requires-Dist: flake8>=5.0.0; python_version == "3.7" and extra == "dev"
Requires-Dist: flake8>=6.0.0; python_version >= "3.8" and 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)
[![CI](https://github.com/DazzleTools/dazzlesum/actions/workflows/python.yml/badge.svg)](https://github.com/DazzleTools/dazzlesum/actions)
[![Python 3.7+](https://img.shields.io/badge/python-3.7+-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)](#installation)

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
- **Native Tool Integration**: Uses system tools (certutil, shasum, fsum) with intelligent Python fallback
- **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.7 or higher
- Operating System: Windows, macOS, Linux, BSD
- Dependencies: None (pure Python standard library)
- Optional: [`unctools` package](https://github.com/djdarcy/UNCtools) for enhanced Windows UNC path support

### 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)

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

# Generate checksums recursively
dazzlesum create -r

# 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
- **Command Prompt**: Full ASCII compatibility
- **PowerShell**: Native support
- **Tools**: Uses `certutil` or `fsum` when available
- **Paths**: Handles UNC paths with optional [`unctools` package](https://github.com/djdarcy/UNCtools)

### macOS/Linux
- **Terminal**: Full compatibility
- **Tools**: Uses `shasum` when available
- **Paths**: Native Unix path handling
- **Performance**: Optimized for large file trees

### Cross-Platform Features
- **Path Normalization**: Automatic path separator handling
- **Line Ending Support**: Configurable line ending strategies
- **Symlink Safety**: Intelligent symlink and junction detection
- **Encoding**: UTF-8 with fallback handling

## Requirements

- **Python**: 3.7 or higher
- **Operating System**: Windows, macOS, Linux, BSD
- **Dependencies**: None (pure Python standard library)
- **Optional**: [`unctools` package](https://github.com/djdarcy/UNCtools) for enhanced Windows UNC path support

## Future Possible Features
- **Incremental Updates**: Smart update detection
- **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

This project is licensed under the GPL-3.0 License - see the [LICENSE](LICENSE) file for details.

## 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.
