🥷 NinjaZipPy

Professional Python .7z Archive Utility
Migrated from the powerful bit7z C++ library

NinjaZipPy is a fast, reliable Python utility for creating and extracting .7z archives. It provides a clean, professional command-line interface with comprehensive functionality for .7z archive operations.

✨ Features

• 🚀 Fast .7z compression and extraction
• 🔐 Password protection support
• 📊 Multiple compression levels (0-9)
• 🎯 Pattern-based file selection
• 📋 Archive information and testing
• 💻 Professional CLI with progress bars
• 🔍 Selective extraction capabilities
• ⚡ Pure Python implementation (no external dependencies)

🛠️ Installation

Prerequisites

• Python 3.7 or higher
• Windows, macOS, or Linux

Install from Source

git clone https://github.com/yourusername/NinjaZipPy.git
cd NinjaZipPy
pip install -e .

Dependencies

NinjaZipPy automatically installs these dependencies:

• py7zr>=0.20.0 - Pure Python 7z implementation
• click>=8.0.0 - Command-line interface framework

🚀 Quick Start

Command Line Usage

📦 Compress Files and Directories

# Using Python module syntax
python -m ninjazipy.cli.main compress archive.7z path\to\file1.txt path\to\folder2

📤 Extract Archives

# Using Python module syntax  
python -m ninjazipy.cli.main extract archive.7z [Output_Folder]

ℹ️ Archive Information

# List files without extracting
ninjazipy extract archive.7z --list

# Using Python module syntax
python -m ninjazipy.cli.main test archive.7z

🧪 Test Archive Integrity

# Using Python module syntax
python -m ninjazipy.cli.main test archive.7z

📖 Detailed Usage Examples

Development and Testing Setup

# 1. Install in development mode
pip install -e .

# 2. Run basic functionality tests
python test_basic1.py
python test_basic2.py

# 3. Check CLI help
ninjazipy --help

# 4. Alternative execution method
python -m ninjazipy.cli.main --help

📋 Command Reference

Information Command

ninjazipy info [OPTIONS] ARCHIVE_PATH

Options:
  -v, --verbose             Show detailed file listing
  --help                    Show help message

Test Command

ninjazipy test [OPTIONS] ARCHIVE_PATH

Options:
  -p, --password TEXT       Password for encrypted archive
  --help                    Show help message

🔍 Troubleshooting

Common Issues

"Archive requires password" Error

# Solution: Provide password with -p flag
ninjazipy extract -p yourpassword archive.7z

"Permission denied" Error

# Solution: Ensure write permissions to output directory
# Or use --overwrite flag to replace existing files
ninjazipy extract archive.7z ./output/ --overwrite

Long Path Names on Windows

# NinjaZipPy automatically handles long paths using pathlib
# No additional configuration needed

Performance Tips

1. Use appropriate compression levels:

   • Level 0-3: Faster compression, larger files
   • Level 5-6: Balanced (recommended)
   • Level 7-9: Maximum compression, slower

2. For large archives:

   • Use verbose mode to monitor progress
   • Ensure sufficient disk space (2x archive size)