# coldpack
Cross-platform cold storage CLI package for standardized tar.zst archives with comprehensive verification.
## Overview
coldpack is a Python CLI package designed for creating standardized cold storage archives. It converts various archive formats (7z, zip, rar, tar.gz, etc.) into a unified tar.zst format with comprehensive verification and recovery mechanisms.
## Features
- **Multi-format Support**: Extract from 11+ archive formats including 7z, zip, rar, tar.gz, tar.bz2, tar.xz
- **Standardized Output**: Unified tar.zst format for long-term storage
- **5-Layer Verification**: TAR header, Zstd integrity, SHA-256, BLAKE3, PAR2 recovery
- **Cross-platform**: Works on Linux, macOS, and Windows
- **High Performance**: Uses par2cmdline-turbo for fast PAR2 operations
- **Rich CLI**: Beautiful progress displays and detailed output
## Installation
### Using uv (Recommended)
```bash
uv add coldpack
```
### Using pip
```bash
pip install coldpack
```
## Requirements
- Python 3.9+
- External tools (automatically installed via PyPI packages):
- `par2cmdline-turbo` for PAR2 operations
- System `tar` command
## Quick Start
### Create a Cold Storage Archive
```bash
# Archive a directory
cpack archive /path/to/source --output-dir /path/to/output
# Archive an existing archive file
cpack archive archive.zip --output-dir /path/to/output
# Custom compression level
cpack archive /path/to/source --compression-level 22 --ultra
```
### Extract an Archive
```bash
# Extract cold storage archive
cpack extract archive.tar.zst --output-dir /path/to/extract
# Extract any supported format
cpack extract archive.7z --output-dir /path/to/extract
```
### Verify Archive Integrity
```bash
# Full 5-layer verification
cpack verify archive.tar.zst
# Quick verification (TAR + Zstd only)
cpack verify archive.tar.zst --quick
```
### Repair Corrupted Archive
```bash
# Repair using PAR2 recovery files
cpack repair archive.tar.zst
```
### Archive Information
```bash
# Display archive metadata
cpack info archive.tar.zst
# List supported formats
cpack formats
```
## Supported Formats
### Input Formats (11 supported)
- `.7z` - 7-Zip archives
- `.zip` - ZIP archives
- `.rar` - RAR archives
- `.tar` - TAR archives
- `.tar.gz`, `.tgz` - Gzip compressed TAR
- `.tar.bz2`, `.tbz2` - Bzip2 compressed TAR
- `.tar.xz`, `.txz` - XZ compressed TAR
- `.tar.zst` - Zstandard compressed TAR
### Output Format
- `.tar.zst` - TAR archive compressed with Zstandard
## Verification Layers
coldpack implements a comprehensive 5-layer verification system:
1. **TAR Header**: Validates TAR archive structure and metadata
2. **Zstd Integrity**: Verifies Zstandard compression integrity
3. **SHA-256**: Cryptographic hash verification (legacy compatibility)
4. **BLAKE3**: Modern cryptographic hash verification
5. **PAR2 Recovery**: Error correction and recovery capability
## Configuration
### Compression Settings
```python
from coldpack import CompressionSettings
# High compression (default)
settings = CompressionSettings(
level=19, # Compression level (1-22)
ultra_mode=False, # Enable ultra mode (levels 20-22)
threads=0, # Auto-detect CPU cores
long_mode=True # Enable long-distance matching
)
# Maximum compression
settings = CompressionSettings(
level=22,
ultra_mode=True,
threads=0
)
```
### Processing Options
```python
from coldpack import ProcessingOptions
options = ProcessingOptions(
verify_integrity=True, # Enable verification
generate_par2=True, # Generate PAR2 files
par2_redundancy=10, # 10% redundancy
cleanup_on_error=True, # Clean up on failure
verbose=True # Detailed output
)
```
## API Usage
```python
from coldpack import ColdStorageArchiver
from pathlib import Path
# Create archiver
archiver = ColdStorageArchiver()
# Create archive
result = archiver.create_archive(
source=Path("/path/to/source"),
output_dir=Path("/path/to/output"),
archive_name="my_archive"
)
if result.success:
print(f"Archive created: {result.archive_path}")
print(f"Original size: {result.metadata.original_size}")
print(f"Compressed size: {result.metadata.compressed_size}")
print(f"Compression ratio: {result.metadata.compression_percentage:.1f}%")
else:
print(f"Archive failed: {result.error}")
```
## Development
### Setup Development Environment
```bash
# Clone repository
git clone <repository-url>
cd coldpack
# Install with uv
uv sync --dev
# Activate environment
source .venv/bin/activate # Linux/macOS
.venv\Scripts\activate # Windows
```
### Development Commands
```bash
# Code formatting
uv run ruff format .
# Linting
uv run ruff check --fix .
# Type checking
uv run mypy src/
# Run tests
uv run pytest
# Run tests with coverage
uv run pytest --cov=src/coldpack --cov-report=html
```
### Project Structure
```
coldpack/
├── src/coldpack/
│ ├── __init__.py # Main API exports
│ ├── cli.py # CLI interface
│ ├── config/ # Configuration management
│ ├── core/ # Core business logic
│ │ ├── archiver.py # Main archiving engine
│ │ ├── extractor.py # Multi-format extraction
│ │ ├── verifier.py # 5-layer verification
│ │ └── repairer.py # PAR2 repair functionality
│ └── utils/ # Utility modules
│ ├── compression.py # Zstd compression
│ ├── hashing.py # Dual hash system
│ ├── par2.py # PAR2 operations
│ ├── filesystem.py # File operations
│ └── progress.py # Progress tracking
├── tests/ # Test suite
├── docs/ # Documentation
└── examples/ # Usage examples
```
## Performance Considerations
- **Large Files**: Uses streaming processing to handle files of any size
- **Memory Usage**: Optimized for minimal memory footprint
- **CPU Utilization**: Automatic multi-threading for compression
- **Disk Space**: Requires ~2x source size for temporary operations
## Security Features
- **Cryptographic Hashing**: Dual hash system (SHA-256 + BLAKE3)
- **Data Integrity**: Multiple verification layers
- **Safe Operations**: Secure temporary file handling
- **Error Recovery**: PAR2-based corruption repair
## Roadmap
- [ ] GUI interface
- [ ] Cloud storage integration
- [ ] Incremental backups
- [ ] Archive encryption
- [ ] Metadata database
- [ ] Network synchronization
## Contributing
1. Fork the repository
2. Create a feature branch
3. Follow the development guidelines
4. Add tests for new functionality
5. Submit a pull request
## License
BSD-3-Clause License. See [LICENSE](LICENSE) for details.
## Support
- Documentation: [CLI Reference](docs/CLI_REFERENCE.md)
- Examples: [Usage Examples](docs/EXAMPLES.md)
- Issues: [GitHub Issues](https://github.com/rxchi1d/coldpack/issues)
---
**coldpack** - Reliable, standardized cold storage for your important data.
Raw data
{
"_id": null,
"home_page": null,
"name": "coldpack",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "archive, backup, cold-storage, compression, tar, zstd",
"author": "coldpack contributors",
"author_email": null,
"download_url": null,
"platform": null,
"description": "# coldpack\n\nCross-platform cold storage CLI package for standardized tar.zst archives with comprehensive verification.\n\n## Overview\n\ncoldpack is a Python CLI package designed for creating standardized cold storage archives. It converts various archive formats (7z, zip, rar, tar.gz, etc.) into a unified tar.zst format with comprehensive verification and recovery mechanisms.\n\n## Features\n\n- **Multi-format Support**: Extract from 11+ archive formats including 7z, zip, rar, tar.gz, tar.bz2, tar.xz\n- **Standardized Output**: Unified tar.zst format for long-term storage\n- **5-Layer Verification**: TAR header, Zstd integrity, SHA-256, BLAKE3, PAR2 recovery\n- **Cross-platform**: Works on Linux, macOS, and Windows\n- **High Performance**: Uses par2cmdline-turbo for fast PAR2 operations\n- **Rich CLI**: Beautiful progress displays and detailed output\n\n## Installation\n\n### Using uv (Recommended)\n\n```bash\nuv add coldpack\n```\n\n### Using pip\n\n```bash\npip install coldpack\n```\n\n## Requirements\n\n- Python 3.9+\n- External tools (automatically installed via PyPI packages):\n - `par2cmdline-turbo` for PAR2 operations\n - System `tar` command\n\n## Quick Start\n\n### Create a Cold Storage Archive\n\n```bash\n# Archive a directory\ncpack archive /path/to/source --output-dir /path/to/output\n\n# Archive an existing archive file\ncpack archive archive.zip --output-dir /path/to/output\n\n# Custom compression level\ncpack archive /path/to/source --compression-level 22 --ultra\n```\n\n### Extract an Archive\n\n```bash\n# Extract cold storage archive\ncpack extract archive.tar.zst --output-dir /path/to/extract\n\n# Extract any supported format\ncpack extract archive.7z --output-dir /path/to/extract\n```\n\n### Verify Archive Integrity\n\n```bash\n# Full 5-layer verification\ncpack verify archive.tar.zst\n\n# Quick verification (TAR + Zstd only)\ncpack verify archive.tar.zst --quick\n```\n\n### Repair Corrupted Archive\n\n```bash\n# Repair using PAR2 recovery files\ncpack repair archive.tar.zst\n```\n\n### Archive Information\n\n```bash\n# Display archive metadata\ncpack info archive.tar.zst\n\n# List supported formats\ncpack formats\n```\n\n## Supported Formats\n\n### Input Formats (11 supported)\n- `.7z` - 7-Zip archives\n- `.zip` - ZIP archives\n- `.rar` - RAR archives\n- `.tar` - TAR archives\n- `.tar.gz`, `.tgz` - Gzip compressed TAR\n- `.tar.bz2`, `.tbz2` - Bzip2 compressed TAR\n- `.tar.xz`, `.txz` - XZ compressed TAR\n- `.tar.zst` - Zstandard compressed TAR\n\n### Output Format\n- `.tar.zst` - TAR archive compressed with Zstandard\n\n## Verification Layers\n\ncoldpack implements a comprehensive 5-layer verification system:\n\n1. **TAR Header**: Validates TAR archive structure and metadata\n2. **Zstd Integrity**: Verifies Zstandard compression integrity\n3. **SHA-256**: Cryptographic hash verification (legacy compatibility)\n4. **BLAKE3**: Modern cryptographic hash verification\n5. **PAR2 Recovery**: Error correction and recovery capability\n\n## Configuration\n\n### Compression Settings\n\n```python\nfrom coldpack import CompressionSettings\n\n# High compression (default)\nsettings = CompressionSettings(\n level=19, # Compression level (1-22)\n ultra_mode=False, # Enable ultra mode (levels 20-22)\n threads=0, # Auto-detect CPU cores\n long_mode=True # Enable long-distance matching\n)\n\n# Maximum compression\nsettings = CompressionSettings(\n level=22,\n ultra_mode=True,\n threads=0\n)\n```\n\n### Processing Options\n\n```python\nfrom coldpack import ProcessingOptions\n\noptions = ProcessingOptions(\n verify_integrity=True, # Enable verification\n generate_par2=True, # Generate PAR2 files\n par2_redundancy=10, # 10% redundancy\n cleanup_on_error=True, # Clean up on failure\n verbose=True # Detailed output\n)\n```\n\n## API Usage\n\n```python\nfrom coldpack import ColdStorageArchiver\nfrom pathlib import Path\n\n# Create archiver\narchiver = ColdStorageArchiver()\n\n# Create archive\nresult = archiver.create_archive(\n source=Path(\"/path/to/source\"),\n output_dir=Path(\"/path/to/output\"),\n archive_name=\"my_archive\"\n)\n\nif result.success:\n print(f\"Archive created: {result.archive_path}\")\n print(f\"Original size: {result.metadata.original_size}\")\n print(f\"Compressed size: {result.metadata.compressed_size}\")\n print(f\"Compression ratio: {result.metadata.compression_percentage:.1f}%\")\nelse:\n print(f\"Archive failed: {result.error}\")\n```\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Clone repository\ngit clone <repository-url>\ncd coldpack\n\n# Install with uv\nuv sync --dev\n\n# Activate environment\nsource .venv/bin/activate # Linux/macOS\n.venv\\Scripts\\activate # Windows\n```\n\n### Development Commands\n\n```bash\n# Code formatting\nuv run ruff format .\n\n# Linting\nuv run ruff check --fix .\n\n# Type checking\nuv run mypy src/\n\n# Run tests\nuv run pytest\n\n# Run tests with coverage\nuv run pytest --cov=src/coldpack --cov-report=html\n```\n\n### Project Structure\n\n```\ncoldpack/\n\u251c\u2500\u2500 src/coldpack/\n\u2502 \u251c\u2500\u2500 __init__.py # Main API exports\n\u2502 \u251c\u2500\u2500 cli.py # CLI interface\n\u2502 \u251c\u2500\u2500 config/ # Configuration management\n\u2502 \u251c\u2500\u2500 core/ # Core business logic\n\u2502 \u2502 \u251c\u2500\u2500 archiver.py # Main archiving engine\n\u2502 \u2502 \u251c\u2500\u2500 extractor.py # Multi-format extraction\n\u2502 \u2502 \u251c\u2500\u2500 verifier.py # 5-layer verification\n\u2502 \u2502 \u2514\u2500\u2500 repairer.py # PAR2 repair functionality\n\u2502 \u2514\u2500\u2500 utils/ # Utility modules\n\u2502 \u251c\u2500\u2500 compression.py # Zstd compression\n\u2502 \u251c\u2500\u2500 hashing.py # Dual hash system\n\u2502 \u251c\u2500\u2500 par2.py # PAR2 operations\n\u2502 \u251c\u2500\u2500 filesystem.py # File operations\n\u2502 \u2514\u2500\u2500 progress.py # Progress tracking\n\u251c\u2500\u2500 tests/ # Test suite\n\u251c\u2500\u2500 docs/ # Documentation\n\u2514\u2500\u2500 examples/ # Usage examples\n```\n\n## Performance Considerations\n\n- **Large Files**: Uses streaming processing to handle files of any size\n- **Memory Usage**: Optimized for minimal memory footprint\n- **CPU Utilization**: Automatic multi-threading for compression\n- **Disk Space**: Requires ~2x source size for temporary operations\n\n## Security Features\n\n- **Cryptographic Hashing**: Dual hash system (SHA-256 + BLAKE3)\n- **Data Integrity**: Multiple verification layers\n- **Safe Operations**: Secure temporary file handling\n- **Error Recovery**: PAR2-based corruption repair\n\n## Roadmap\n\n- [ ] GUI interface\n- [ ] Cloud storage integration\n- [ ] Incremental backups\n- [ ] Archive encryption\n- [ ] Metadata database\n- [ ] Network synchronization\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Follow the development guidelines\n4. Add tests for new functionality\n5. Submit a pull request\n\n## License\n\nBSD-3-Clause License. See [LICENSE](LICENSE) for details.\n\n## Support\n\n- Documentation: [CLI Reference](docs/CLI_REFERENCE.md)\n- Examples: [Usage Examples](docs/EXAMPLES.md)\n- Issues: [GitHub Issues](https://github.com/rxchi1d/coldpack/issues)\n\n---\n\n**coldpack** - Reliable, standardized cold storage for your important data.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Cross-platform cold storage CLI package for standardized tar.zst archives with comprehensive verification",
"version": "0.1.0b2",
"project_urls": {
"Homepage": "https://github.com/rxchi1d/coldpack",
"Issues": "https://github.com/rxchi1d/coldpack/issues",
"Repository": "https://github.com/rxchi1d/coldpack"
},
"split_keywords": [
"archive",
" backup",
" cold-storage",
" compression",
" tar",
" zstd"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "29b8e87041d19538110ac6823a3a74bbaf34e70a4ac015a928788aa1cb44963d",
"md5": "cf2a03265c516eae2bbf7a196608e1e5",
"sha256": "3f07b45e30e7e1c30709f4d36ec591e6d424f069784135aa0ac30a7a8cde1136"
},
"downloads": -1,
"filename": "coldpack-0.1.0b2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cf2a03265c516eae2bbf7a196608e1e5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 80650,
"upload_time": "2025-07-24T15:45:10",
"upload_time_iso_8601": "2025-07-24T15:45:10.631395Z",
"url": "https://files.pythonhosted.org/packages/29/b8/e87041d19538110ac6823a3a74bbaf34e70a4ac015a928788aa1cb44963d/coldpack-0.1.0b2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-24 15:45:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rxchi1d",
"github_project": "coldpack",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "coldpack"
}
JSON
