archive-extractor 0.1.2__tar.gz → 0.2.0__tar.gz

archive_extractor-0.2.0/CLAUDE.md

@@ -0,0 +1,65 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Archive Extractor is a Python library and CLI tool that recursively searches for and extracts ZIP and 7z archives within a directory tree. It handles password-protected archives, preserves folder structures, and prevents path traversal attacks.
+
+## Architecture
+
+This is a Python package (`archive_extractor/`) with the following structure:
+
+- **`archive_extractor/__init__.py`**: Public API and CLI entry point
+  - `extract_archives()`: Main library function for programmatic use
+  - `main()`: CLI entry point for command-line usage
+- **`archive_extractor/core.py`**: Core extraction logic
+  - `sanitize_filename()`: Path security
+  - `find_archive_files()`: Archive discovery generator
+  - `load_passwords()`: Password file parsing
+  - `extract_zip_archive()`: ZIP extraction with password support
+  - `extract_7z_archive()`: 7z extraction with password support
+
+## Key Dependencies
+
+- `zipfile` (stdlib): ZIP extraction
+- `py7zr`: 7z archive extraction
+- `tqdm`: Progress bars during extraction
+- `lzma` (stdlib): Referenced in exception handling for 7z corruption detection
+
+## Development Commands
+
+**Install as a tool**:
+```bash
+uv tool install .
+```
+
+**Run directly**:
+```bash
+python -m archive_extractor /path/to/search
+python -m archive_extractor /path/to/search --passwords passwords.txt
+```
+
+**Install in editable mode for development**:
+```bash
+uv pip install -e .
+```
+
+**Library usage**:
+```python
+from archive_extractor import extract_archives
+results = extract_archives("/path/to/search", passwords=["pass1", "pass2"])
+```
+
+## Important Implementation Notes
+
+- Extracted files are placed in directories named after each archive (without the archive extension)
+- Path safety is enforced at extraction time: absolute paths and paths containing `..` are skipped
+- For password-protected archives, the tool tries each password in sequence and stops at the first successful extraction
+- Error handling is intentionally broad (catching generic `Exception`) to ensure the tool continues processing other archives even if one fails
+- The `lzma.LZMAError` exception is caught to handle corrupt 7z archives
+- The `extract_archives()` function returns a dictionary mapping archive paths to extraction counts (-1 for failures)
+
+## README Requirements
+
+README.md must be kept up to date with any significant project changes, including new archive format support, command-line options, or security-related improvements.

{archive_extractor-0.1.2 → archive_extractor-0.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: archive-extractor
-Version: 0.1.2
-Summary: 📦 Recursively extract ZIP and 7z archives from directory trees, with password-cracking support
+Version: 0.2.0
+Summary: Recursively extract ZIP and 7z archives from directory trees, with password-cracking support
 Author-email: Tiago Silva <eng.tiago.silva@gmail.com>
 License-File: LICENSE
 Requires-Python: >=3.12

{archive_extractor-0.1.2 → archive_extractor-0.2.0}/README.md

@@ -3,7 +3,7 @@
 
   # archive-extractor
 
-  [![Python](https://img.shields.io/badge/Python-3.7+-blue.svg)](https://www.python.org/)
+  [![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://www.python.org/)
   [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
   [![PyPI](https://img.shields.io/pypi/v/archive-extractor)](https://pypi.org/project/archive-extractor/)
 
@@ -14,7 +14,7 @@
 
 ## Overview
 
-archive-extractor is a command-line tool for bulk extraction of archives nested within directory trees. It discovers and extracts `.zip` and `.7z` files, handles password-protected archives using a wordlist, and includes security measures against path traversal attacks.
+archive-extractor is a Python library and CLI tool for bulk extraction of archives nested within directory trees. It discovers and extracts `.zip` and `.7z` files, handles password-protected archives using a wordlist, and includes security measures against path traversal attacks.
 
 Ideal for bulk extraction tasks or forensic analysis where archives may be deeply nested or encrypted.
 
@@ -25,6 +25,7 @@ Ideal for bulk extraction tasks or forensic analysis where archives may be deepl
 - **🛡️ Path traversal protection** - Sanitizes filenames and rejects unsafe paths
 - **📊 Progress indicators** - Shows extraction progress with tqdm
 - **📁 Preserves structure** - Extracts each archive into its own named folder
+- **📚 Library API** - Use programmatically in your Python projects
 
 ## Installation
 
@@ -40,6 +41,8 @@ uv pip install -e .
 
 ## Usage
 
+### 🖥️ CLI
+
 Extract all archives under a directory:
 
 ```bash
@@ -52,11 +55,48 @@ Extract with a password list (one password per line):
 archive-extractor /path/to/search --passwords passwords.txt
 ```
 
+Extract to a custom output directory:
+
+```bash
+archive-extractor /path/to/search --output-dir /path/to/output
+```
+
+Quiet mode (suppress progress output):
+
+```bash
+archive-extractor /path/to/search --quiet
+```
+
+### 📚 Library
+
+Use archive-extractor programmatically in your Python projects:
+
+```python
+from archive_extractor import extract_archives
+
+# Extract all archives in a directory
+results = extract_archives("/path/to/search")
+
+# Extract a single archive
+results = extract_archives("/path/to/archive.zip")
+
+# With passwords
+results = extract_archives("/path/to/search", passwords=["pass1", "pass2"])
+
+# Custom output directory
+results = extract_archives("/path/to/search", output_dir="/path/to/output")
+
+# Silent mode (no progress bars)
+results = extract_archives("/path/to/search", show_progress=False)
+```
+
+The `extract_archives()` function returns a dictionary mapping archive paths to extraction counts (-1 indicates failure).
+
 ### Output
 
 - Archives extract to folders named after the archive file (without extension)
-- Success: `✅ Extracted 'archive.7z' to 'archive'.`
-- Failure: `❌ Could not extract 'archive.zip': no valid password found.`
+- Success: `Extracted 'archive.7z' to 'archive'.`
+- Failure: `Could not extract 'archive.zip': no valid password found or archive is corrupt.`
 
 ## Security
 

archive_extractor-0.2.0/archive_extractor/__init__.py

@@ -0,0 +1,118 @@
+"""Archive Extractor - Recursively extract ZIP and 7z archives.
+
+CLI Usage:
+    archive-extractor /path/to/search
+    archive-extractor /path/to/search --passwords passwords.txt
+
+Library Usage:
+    from archive_extractor import extract_archives
+
+    # Extract all archives in a directory
+    results = extract_archives("/path/to/search")
+
+    # Extract a single archive
+    results = extract_archives("/path/to/archive.zip")
+
+    # With passwords
+    results = extract_archives("/path/to/search", passwords=["pass1", "pass2"])
+
+    # Custom output directory
+    results = extract_archives("/path/to/search", output_dir="/path/to/output")
+
+    # Silent mode (no progress bars)
+    results = extract_archives("/path/to/search", show_progress=False)
+"""
+
+import argparse
+import os
+
+from .core import (
+    find_archive_files,
+    load_passwords,
+    extract_zip_archive,
+    extract_7z_archive,
+)
+
+__all__ = ["extract_archives"]
+
+
+def extract_archives(
+    path: str,
+    output_dir: str | None = None,
+    passwords: list[str] | None = None,
+    show_progress: bool = True
+) -> dict[str, int]:
+    """Extract all archives found at the given path.
+
+    Args:
+        path: Single archive file or directory to search for archives.
+        output_dir: Optional base directory for extraction output.
+            If None, each archive extracts to a sibling directory named after the archive.
+        passwords: Optional list of password strings to try for encrypted archives.
+        show_progress: Whether to show progress bars during extraction.
+
+    Returns:
+        Dictionary mapping archive paths to extraction counts.
+        A count of -1 indicates extraction failure.
+    """
+    results = {}
+
+    for archive_path in find_archive_files(path):
+        if output_dir:
+            archive_name = os.path.splitext(os.path.basename(archive_path))[0]
+            dest_dir = os.path.join(output_dir, archive_name)
+        else:
+            dest_dir = os.path.splitext(archive_path)[0]
+
+        ext = os.path.splitext(archive_path)[1].lower()
+
+        if ext == ".zip":
+            count = extract_zip_archive(archive_path, dest_dir, passwords, show_progress)
+        elif ext == ".7z":
+            count = extract_7z_archive(archive_path, dest_dir, passwords, show_progress)
+        else:
+            continue
+
+        results[archive_path] = count
+
+        if show_progress:
+            if count >= 0:
+                print(f"Extracted '{archive_path}' to '{dest_dir}'.")
+            else:
+                print(f"Could not extract '{archive_path}': no valid password found or archive is corrupt.")
+
+    return results
+
+
+def main():
+    """CLI entry point for archive-extractor."""
+    parser = argparse.ArgumentParser(
+        description="Recursively extract all files from .zip and .7z archives under a given path."
+    )
+    parser.add_argument(
+        "path",
+        help="Root directory or file to search for .zip/.7z files"
+    )
+    parser.add_argument(
+        "--passwords",
+        help="Path to a file containing passwords (one per line) to try for encrypted archives"
+    )
+    parser.add_argument(
+        "--output-dir",
+        help="Base directory for extraction output (default: sibling directory of each archive)"
+    )
+    parser.add_argument(
+        "--quiet", "-q",
+        action="store_true",
+        help="Suppress progress output"
+    )
+    args = parser.parse_args()
+
+    passwords = load_passwords(args.passwords) if args.passwords else None
+
+    extract_archives(
+        args.path,
+        output_dir=args.output_dir,
+        passwords=passwords,
+        show_progress=not args.quiet
+    )

archive_extractor-0.2.0/archive_extractor/core.py

@@ -0,0 +1,160 @@
+"""Core extraction logic for archive-extractor."""
+
+import os
+import re
+import zipfile
+import lzma
+
+import py7zr
+from tqdm import tqdm
+
+
+def sanitize_filename(filename: str) -> str:
+    """Remove directories and illegal characters from a filename.
+
+    Args:
+        filename: The filename to sanitize.
+
+    Returns:
+        A safe filename with illegal characters replaced and path components removed.
+    """
+    filename = re.sub(r'[\\/*?:"<>|]', "_", filename)
+    filename = filename.replace("..", "")
+    return os.path.basename(filename)
+
+
+def find_archive_files(root_path: str):
+    """Recursively yield paths to all .zip and .7z files under root_path.
+
+    Args:
+        root_path: Directory to search, or a single archive file path.
+
+    Yields:
+        Absolute paths to archive files found.
+    """
+    if os.path.isfile(root_path):
+        ext = os.path.splitext(root_path)[1].lower()
+        if ext in ('.zip', '.7z'):
+            yield root_path
+        return
+
+    for dirpath, _, filenames in os.walk(root_path):
+        for fname in filenames:
+            if fname.lower().endswith('.zip') or fname.lower().endswith('.7z'):
+                yield os.path.join(dirpath, fname)
+
+
+def load_passwords(password_file: str) -> list[str]:
+    """Load passwords from a file, one per line, stripping whitespace.
+
+    Args:
+        password_file: Path to a file containing passwords.
+
+    Returns:
+        List of password strings.
+    """
+    with open(password_file, 'r', encoding='utf-8') as f:
+        return [line.strip() for line in f if line.strip()]
+
+
+def extract_zip_archive(
+    zip_file: str,
+    output_dir: str,
+    passwords: list[str] | None = None,
+    show_progress: bool = True
+) -> int:
+    """Extract a ZIP archive to the specified directory.
+
+    Args:
+        zip_file: Path to the ZIP file.
+        output_dir: Directory to extract files to.
+        passwords: Optional list of passwords to try for encrypted archives.
+        show_progress: Whether to show tqdm progress bar.
+
+    Returns:
+        Number of files extracted, or -1 on failure.
+    """
+    if not os.path.exists(output_dir):
+        os.makedirs(output_dir)
+
+    with zipfile.ZipFile(zip_file, 'r') as zf:
+        members = zf.infolist()
+        extracted_count = 0
+
+        def extract_members(pwd_bytes=None):
+            nonlocal extracted_count
+            iterator = tqdm(members, desc=f"Extracting {os.path.basename(zip_file)}", leave=False) if show_progress else members
+            for member in iterator:
+                if member.is_dir():
+                    continue
+                safe_member_path = os.path.normpath(member.filename)
+                if os.path.isabs(safe_member_path) or safe_member_path.startswith(".."):
+                    continue
+                out_path = os.path.join(output_dir, safe_member_path)
+                out_dir = os.path.dirname(out_path)
+                if not os.path.exists(out_dir):
+                    os.makedirs(out_dir)
+                with open(out_path, 'wb') as f:
+                    f.write(zf.read(member, pwd_bytes))
+                extracted_count += 1
+
+        if not passwords:
+            try:
+                extract_members()
+                return extracted_count
+            except RuntimeError:
+                return -1
+        else:
+            for pwd in passwords:
+                extracted_count = 0
+                try:
+                    extract_members(pwd.encode('utf-8'))
+                    return extracted_count
+                except RuntimeError:
+                    continue
+                except zipfile.BadZipFile:
+                    continue
+            return -1
+
+
+def extract_7z_archive(
+    archive_file: str,
+    output_dir: str,
+    passwords: list[str] | None = None,
+    show_progress: bool = True
+) -> int:
+    """Extract a 7z archive to the specified directory.
+
+    Args:
+        archive_file: Path to the 7z file.
+        output_dir: Directory to extract files to.
+        passwords: Optional list of passwords to try for encrypted archives.
+        show_progress: Whether to show tqdm progress bar (currently unused for 7z).
+
+    Returns:
+        Number of files extracted, or -1 on failure.
+    """
+    if not os.path.exists(output_dir):
+        os.makedirs(output_dir)
+
+    def try_extract(password=None):
+        with py7zr.SevenZipFile(archive_file, mode='r', password=password) as archive:
+            archive.extractall(path=output_dir)
+            return len(archive.getnames())
+
+    if not passwords:
+        try:
+            return try_extract()
+        except (py7zr.exceptions.PasswordRequired, py7zr.exceptions.Bad7zFile, lzma.LZMAError):
+            return -1
+        except Exception:
+            return -1
+    else:
+        for pwd in passwords:
+            try:
+                return try_extract(pwd)
+            except (py7zr.exceptions.PasswordRequired, py7zr.exceptions.Bad7zFile, lzma.LZMAError):
+                continue
+            except Exception:
+                continue
+        return -1

{archive_extractor-0.1.2 → archive_extractor-0.2.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "archive-extractor"
-version = "0.1.2"
-description = "📦 Recursively extract ZIP and 7z archives from directory trees, with password-cracking support"
+version = "0.2.0"
+description = "Recursively extract ZIP and 7z archives from directory trees, with password-cracking support"
 authors = [
     { name = "Tiago Silva", email = "eng.tiago.silva@gmail.com" }
 ]
@@ -16,7 +16,4 @@ dependencies = [
 requires-python = ">=3.12"
 
 [project.scripts]
-archive-extractor = "main:main"
-
-[tool.hatch.build.targets.wheel]
-include = ["main.py"]
+archive-extractor = "archive_extractor:main"

archive_extractor-0.1.2/CLAUDE.md

@@ -1,54 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-Archive Extractor is a command-line utility that recursively searches for and extracts ZIP and 7z archives within a directory tree. It handles password-protected archives, preserves folder structures, and prevents path traversal attacks.
-
-## Architecture
-
-This is a single-module Python CLI tool (`main.py`) with a straightforward architecture:
-
-- **Entry point**: `main()` function parses arguments and orchestrates archive discovery and extraction
-- **Archive discovery**: `find_archive_files()` walks the directory tree to locate .zip and .7z files
-- **Extraction logic**: Separate functions for ZIP (`extract_zip()`) and 7z (`extract_7z()`) formats
-- **Password handling**: `load_passwords()` reads password lists; extraction functions attempt each password sequentially until success
-- **Security**: `sanitize_filename()` prevents directory traversal; extraction functions validate paths with `os.path.normpath()` and reject absolute paths or `..` sequences
-
-## Key Dependencies
-
-- `zipfile` (stdlib): ZIP extraction
-- `py7zr`: 7z archive extraction
-- `tqdm`: Progress bars during extraction
-- `lzma`: Referenced in exception handling for 7z corruption detection (note: currently imported but not directly used due to py7zr wrapping it)
-
-## Development Commands
-
-**Install as a tool**:
-```bash
-uv tool install .
-```
-
-**Run directly**:
-```bash
-python main.py /path/to/search
-python main.py /path/to/search --passwords passwords.txt
-```
-
-**Install in editable mode for development**:
-```bash
-uv pip install -e .
-```
-
-## Important Implementation Notes
-
-- Extracted files are placed in directories named after each archive (without the archive extension)
-- Path safety is enforced at extraction time: absolute paths and paths containing `..` are skipped
-- For password-protected archives, the tool tries each password in sequence and stops at the first successful extraction
-- Error handling is intentionally broad (catching generic `Exception`) to ensure the tool continues processing other archives even if one fails
-- The `lzma.LZMAError` exception is caught to handle corrupt 7z archives, though `lzma` is no longer a direct dependency (handled internally by py7zr)
-
-## README Requirements
-
-README.md must be kept up to date with any significant project changes, including new archive format support, command-line options, or security-related improvements.

archive_extractor-0.1.2/main.py

@@ -1,131 +0,0 @@
-import os
-import re
-import argparse
-from tqdm import tqdm
-import zipfile
-import py7zr
-import lzma
-
-def sanitize_filename(filename):
-    # Remove directories and illegal characters
-    filename = re.sub(r'[\\/*?:"<>|]', "_", filename)
-    filename = filename.replace("..", "")  # extra safety
-    return os.path.basename(filename)
-
-def find_archive_files(root_path):
-    """Recursively yield paths to all .zip and .7z files under root_path."""
-    for dirpath, _, filenames in os.walk(root_path):
-        for fname in filenames:
-            if fname.lower().endswith('.zip') or fname.lower().endswith('.7z'):
-                yield os.path.join(dirpath, fname)
-
-def load_passwords(password_file):
-    """Load passwords from a file, one per line, stripping whitespace."""
-    with open(password_file, 'r', encoding='utf-8') as f:
-        return [line.strip() for line in f if line.strip()]
-
-def extract_zip(zip_file, output_dir, passwords=None):
-    if not os.path.exists(output_dir):
-        os.makedirs(output_dir)
-
-    with zipfile.ZipFile(zip_file, 'r') as zf:
-        members = zf.infolist()
-        extracted = False
-        if not passwords:
-            # No passwords provided, extract directly
-            for member in tqdm(members, desc=f"Extracting {os.path.basename(zip_file)}"):
-                if member.is_dir():
-                    continue
-                safe_member_path = os.path.normpath(member.filename)
-                if os.path.isabs(safe_member_path) or safe_member_path.startswith(".."):
-                    continue
-                out_path = os.path.join(output_dir, safe_member_path)
-                out_dir = os.path.dirname(out_path)
-                if not os.path.exists(out_dir):
-                    os.makedirs(out_dir)
-                with open(out_path, 'wb') as f:
-                    f.write(zf.read(member))
-            extracted = True
-        else:
-            # Try each password for the whole zip
-            for pwd in passwords:
-                try:
-                    for member in tqdm(members, desc=f"Extracting {os.path.basename(zip_file)}", leave=False):
-                        if member.is_dir():
-                            continue
-                        safe_member_path = os.path.normpath(member.filename)
-                        if os.path.isabs(safe_member_path) or safe_member_path.startswith(".."):
-                            continue
-                        out_path = os.path.join(output_dir, safe_member_path)
-                        out_dir = os.path.dirname(out_path)
-                        if not os.path.exists(out_dir):
-                            os.makedirs(out_dir)
-                        with open(out_path, 'wb') as f:
-                            f.write(zf.read(member, pwd.encode('utf-8')))
-                    extracted = True
-                    break  # Stop trying passwords after success
-                except RuntimeError:
-                    # Wrong password, try next
-                    continue
-                except zipfile.BadZipFile:
-                    continue
-        if not extracted:
-            print(f"❌ Could not extract '{zip_file}': no valid password found.")
-        else:
-            print(f"✅ Extracted {len(members)} items to '{output_dir}'.")
-
-def extract_7z(archive_file, output_dir, passwords=None):
-    if not os.path.exists(output_dir):
-        os.makedirs(output_dir)
-
-    extracted = False
-    if not passwords:
-        try:
-            with py7zr.SevenZipFile(archive_file, mode='r') as archive:
-                archive.extractall(path=output_dir)
-            extracted = True
-        except (py7zr.exceptions.PasswordRequired, py7zr.exceptions.Bad7zFile, lzma.LZMAError):
-            pass
-        except Exception:
-            pass
-    else:
-        for pwd in passwords:
-            try:
-                with py7zr.SevenZipFile(archive_file, mode='r', password=pwd) as archive:
-                    archive.extractall(path=output_dir)
-                extracted = True
-                break
-            except (py7zr.exceptions.PasswordRequired, py7zr.exceptions.Bad7zFile, lzma.LZMAError):
-                continue
-            except Exception:
-                continue
-    if not extracted:
-        print(f"❌ Could not extract '{archive_file}': no valid password found or archive is corrupt.")
-    else:
-        print(f"✅ Extracted '{archive_file}' to '{output_dir}'.")
-
-def main():
-    parser = argparse.ArgumentParser(
-        description="Recursively extract all files from .zip and .7z archives under a given path."
-    )
-    parser.add_argument(
-        "path",
-        help="Root directory or file to search for .zip/.7z files"
-    )
-    parser.add_argument(
-        "--passwords",
-        help="Path to a file containing passwords (one per line) to try for encrypted archives"
-    )
-    args = parser.parse_args()
-    root_path = args.path
-    passwords = load_passwords(args.passwords) if args.passwords else None
-    for archive_path in find_archive_files(root_path):
-        archive_dir = os.path.splitext(archive_path)[0]
-        ext = os.path.splitext(archive_path)[1].lower()
-        if ext == ".zip":
-            extract_zip(archive_path, archive_dir, passwords)
-        elif ext == ".7z":
-            extract_7z(archive_path, archive_dir, passwords)
-
-if __name__ == "__main__":
-    main()