Metadata-Version: 2.4
Name: coldpack
Version: 0.5.0
Summary: Professional 7z Cold Storage Solution with Revolutionary Architecture - Advanced CLI tool for creating standardized 7z archives with comprehensive verification, PAR2 recovery, and intelligent cross-platform compatibility.
Project-URL: Homepage, https://github.com/rxchi1d/coldpack
Project-URL: Repository, https://github.com/rxchi1d/coldpack
Project-URL: Issues, https://github.com/rxchi1d/coldpack/issues
Project-URL: Discussions, https://github.com/rxchi1d/coldpack/discussions
Project-URL: Documentation, https://github.com/rxchi1d/coldpack#readme
Project-URL: Changelog, https://github.com/rxchi1d/coldpack/blob/main/CHANGELOG.md
Author: coldpack contributors
Maintainer: coldpack team
License: MIT License
        
        Copyright (c) 2025 coldpack contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: 7z,archive,backup,blake3,cli,cold-storage,compression,cross-platform,enterprise,integrity,par2,professional,recovery,sha256,verification
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
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: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Archiving :: Backup
Classifier: Topic :: System :: Archiving :: Compression
Classifier: Topic :: System :: Recovery Tools
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Requires-Dist: blake3>=1.0.5
Requires-Dist: loguru>=0.7.0
Requires-Dist: par2cmdline-turbo>=1.3.0
Requires-Dist: py7zz==1.1.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=14.0.0
Requires-Dist: toml>=0.10.0
Requires-Dist: tomli>=1.2.0; python_full_version < '3.11'
Requires-Dist: typer>=0.16.0
Provides-Extra: dev
Description-Content-Type: text/markdown

<!--
SPDX-FileCopyrightText: 2025 coldpack contributors
SPDX-License-Identifier: MIT
-->

# coldpack

[![PyPI version](https://badge.fury.io/py/coldpack.svg)](https://badge.fury.io/py/coldpack)
[![Python Support](https://img.shields.io/pypi/pyversions/coldpack.svg)](https://pypi.org/project/coldpack/)
[![Platform Support](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)](https://github.com/rxchi1d/coldpack)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![CI Status](https://github.com/rxchi1d/coldpack/workflows/CI/badge.svg)](https://github.com/rxchi1d/coldpack/actions)

[English](README.md) | [繁體中文](README.zh-tw.md)

A Python CLI tool for creating standardized 7z archives for long-term data storage with integrity verification, PAR2 recovery, and cross-platform compatibility.

## Overview

coldpack is a command-line tool for creating standardized cold storage archives. It converts various source formats (directories, zip, tar, etc.) into 7z archives with integrated verification and recovery mechanisms designed for long-term data preservation.

## Features

### Core Functionality
- **7z-only output**: Converts various input formats to standardized 7z archives
- **Adaptive compression**: Automatically selects compression parameters based on file size
- **Command-line interface**: Simple CLI commands for archive management

### Available Commands
- **`cpack create`** - Create 7z cold storage archives
- **`cpack extract`** - Extract archives with parameter restoration
- **`cpack verify`** - Verify archive integrity using multiple methods
- **`cpack repair`** - Repair corrupted archives using PAR2 recovery
- **`cpack info`** - Display archive metadata
- **`cpack list`** - List archive contents with filtering options

### Verification and Recovery
- **Multiple verification layers**: 7z integrity, SHA-256, BLAKE3, and PAR2
- **Dual hash algorithms**: SHA-256 for compatibility, BLAKE3 for performance
- **PAR2 recovery files**: 10% redundancy for error correction
- **Metadata preservation**: Stores compression parameters in metadata.toml

### Cross-Platform Support
- **Operating systems**: Windows, macOS, Linux
- **System file handling**: Automatically excludes platform-specific files (.DS_Store, Thumbs.db)
- **Unicode support**: Handles international filenames correctly with automatic compatibility
- **Progress tracking**: Real-time progress display during operations

For detailed installation and usage instructions, see [Installation Guide](docs/INSTALLATION.md) and [CLI Reference](docs/CLI_REFERENCE.md).

## Quick Start

### Installation

```bash
# Using pip (recommended)
pip install coldpack

# Using uv
uv add coldpack
```

**Requirements**: Python 3.9+ | Windows, macOS, Linux

For detailed installation instructions including development setup, see [Installation Guide](docs/INSTALLATION.md).

### Basic Usage

```bash
# Create 7z cold storage archive
cpack create /path/to/documents --output-dir ~/cold-storage

# Extract with automatic parameter recovery
cpack extract ~/cold-storage/documents.7z --output-dir ~/restored

# Verify 4-layer integrity
cpack verify ~/cold-storage/documents.7z

# Advanced file listing with filtering
cpack list ~/cold-storage/documents.7z --filter "*.pdf" --limit 10
```

### Advanced Usage

```bash
# Custom compression levels (0-9) with memory limit
cpack create large-dataset/ --level 9 --dict 512m --memory-limit 2g --output-dir ~/archives

# Memory-constrained compression for limited systems
cpack create documents/ --memory-limit 512m --output-dir ~/archives

# Pre-verification before extraction
cpack extract suspicious-archive.7z --verify --output-dir ~/safe-extraction

# Repair corrupted files using PAR2
cpack repair ~/cold-storage/damaged-archive.7z

# Display metadata information
cpack info ~/cold-storage/documents.7z
```

See [Usage Examples](docs/EXAMPLES.md) for more use cases and workflows.

## Technical Specifications

### Supported Input Formats
- **Directories**: Any filesystem directory structure
- **Archive Formats**: 7z, zip, rar, tar, tar.gz, tar.bz2, tar.xz, tar.zst

### Output Structure
```
archive-name/
├── archive-name.7z              # Main 7z archive
├── archive-name.7z.sha256       # SHA-256 hash
├── archive-name.7z.blake3       # BLAKE3 hash
├── archive-name.7z.par2         # PAR2 recovery files
└── metadata/
    └── metadata.toml            # Complete archive metadata
```

### Verification System

1. **7z Integrity**: Native 7z archive structure validation
2. **SHA-256**: Cryptographic hash verification (legacy compatibility)
3. **BLAKE3**: Modern high-performance cryptographic hash
4. **PAR2 Recovery**: Error correction with 10% redundancy

### Compression Optimization

| File Size Range | Compression Level | Dictionary Size | Use Case |
|-----------------|-------------------|-----------------|----------|
| < 256 KiB | Level 1 | 128k | Minimal resources |
| 256 KiB – 1 MiB | Level 3 | 1m | Light compression |
| 1 – 8 MiB | Level 5 | 4m | Balanced performance |
| 8 – 64 MiB | Level 6 | 16m | Good compression |
| 64 – 512 MiB | Level 7 | 64m | High compression |
| 512 MiB – 2 GiB | Level 9 | 256m | Maximum compression |
| > 2 GiB | Level 9 | 512m | Maximum efficiency |

For detailed architecture documentation and configuration options, see [Architecture Guide](docs/ARCHITECTURE.md).

## Development & Contributing

### Development Setup

```bash
# Clone and setup development environment
git clone https://github.com/rxchi1d/coldpack.git
cd coldpack
uv sync --dev
source .venv/bin/activate
```

### Quality Assurance

```bash
# Code formatting and linting
uv run ruff format . && uv run ruff check --fix .

# Type checking and testing
uv run mypy src/ && uv run pytest
```

**Development Standards**: Comprehensive test suite, ruff formatting, MyPy type checking, cross-platform CI/CD

See [CLAUDE.md](CLAUDE.md) for complete development instructions.


## License & Support

**License**: MIT - See [LICENSE](LICENSE) and [LICENSES/MIT.txt](LICENSES/MIT.txt) for details
**Third-party Dependencies**: This project does not redistribute 7-Zip binaries; runtime dependencies (py7zz, PAR2 tools) are installed by users and governed by their upstream licenses.

**Documentation**:
- [Installation Guide](docs/INSTALLATION.md) - Setup instructions
- [CLI Reference](docs/CLI_REFERENCE.md) - Command documentation
- [Usage Examples](docs/EXAMPLES.md) - Use cases and workflows
- [Architecture Guide](docs/ARCHITECTURE.md) - Technical implementation details

**Support**: [GitHub Issues](https://github.com/rxchi1d/coldpack/issues) | [Discussions](https://github.com/rxchi1d/coldpack/discussions)
