archae 2026.1.0__py3-none-any.whl

archae/__init__.py

@@ -0,0 +1 @@
+"""Archae explodes archives."""

archae/__main__.py

@@ -0,0 +1,9 @@
+"""archae as a module entry point.
+
+This allows archae to be executable from a git checkout or zip archive.
+"""
+
+from .cli import cli
+
+if __name__ == "__main__":
+    cli()

archae/cli.py

@@ -0,0 +1,374 @@
+"""Main CLI for archae."""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import re
+import shutil
+from importlib import metadata
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import magic
+import rich_click as click
+
+import archae.util.archiver
+from archae.util.enum import ByteScale
+
+if TYPE_CHECKING:
+    from archae.util.archiver.base_archiver import BaseArchiver
+
+tools: dict[str, BaseArchiver] = {}
+
+
+class FileSizeParamType(click.ParamType):
+    """Class to handle FileSize as a Click Param."""
+
+    name = "filesize"
+
+    @staticmethod
+    def compact_value(value: float) -> str:
+        """Convert a float of file size to a FileSizeParam string.
+
+        Args:
+            value (float): The size to convert
+
+        Returns:
+            str: A string with the most collapsed exact byte size rep.
+
+        """
+        exponent = 0
+        modulo: float = 0
+        while modulo == 0 and exponent < int(ByteScale.PETA.value):
+            modulo = value % 1024
+            if modulo == 0:
+                exponent += 1
+                value = int(value / 1024)
+        return f"{value}{ByteScale(exponent).prefix_letter}"  # type: ignore[call-arg]
+
+    @staticmethod
+    def expand_value(value: str | int) -> int:
+        """Convert a FileSizeParam string or int to an int.
+
+        Args:
+            value (str | int): The value to convert as necessary.
+
+        Returns:
+            int: Size in bytes
+
+        """
+        try:
+            return int(value)
+        except ValueError:
+            pass
+
+        # Regex to split number and unit
+        match = re.match(r"^(\d+(?:\.\d+)?)\s*([KMGT]B?)$", str(value), re.IGNORECASE)
+        if not match:
+            msg = f"{value} is not a valid file size (e.g., 10G, 500M)"
+            raise ValueError(msg)
+
+        number, unit = match.groups()
+        number = float(number)
+        unit = unit.upper()
+
+        units = {
+            "K": 1024,
+            "KB": 1024,
+            "M": 1024**2,
+            "MB": 1024**2,
+            "G": 1024**3,
+            "GB": 1024**3,
+            "T": 1024**4,
+            "TB": 1024**4,
+        }
+
+        # Default to bytes if no specific unit multiplier, or assume B
+        return int(number * units.get(unit, 1))
+
+    def convert(self, value: click.Option, param: str, ctx: click.Context) -> int:
+        """Convert a FileSizeParam to an int.
+
+        Args:
+            value (click.Option): The value to convert as necessary.
+            param (str): The param we are validating.
+            ctx (click.Context): The click Context to fail if we can't parse it.
+
+        Returns:
+            int: Size in bytes
+
+        """
+        try:
+            return self.expand_value(value)
+        except ValueError as err:
+            self.fail(str(err), param, ctx)
+            return 0
+
+
+defaults = {
+    "max_total_size_bytes": FileSizeParamType.expand_value("100G"),
+    "max_archive_size_bytes": FileSizeParamType.expand_value("10G"),
+    "min_archive_ratio": 0.005,
+}
+
+config = copy.deepcopy(defaults)
+
+
+@click.command(
+    context_settings={"help_option_names": ["-h", "--help"], "show_default": True}
+)
+@click.rich_config(
+    help_config=click.RichHelpConfiguration(
+        width=88,
+        show_arguments=True,
+        text_markup=True,
+    ),
+)
+@click.argument(
+    "archive_path",
+    type=click.Path(exists=True, dir_okay=False),
+    help="Archive to examine",
+)
+@click.option(
+    "--max_total_size_bytes",
+    type=FileSizeParamType(),
+    default=defaults["max_total_size_bytes"],
+    help=f"Maximum total extraction size before failing, default {FileSizeParamType.compact_value(defaults['max_total_size_bytes'])}",
+)
+@click.option(
+    "--max_archive_size_bytes",
+    type=FileSizeParamType(),
+    default=defaults["max_archive_size_bytes"],
+    help=f"Maximum individual archive extraction size before failing, default {FileSizeParamType.compact_value(defaults['max_archive_size_bytes'])}",
+)
+@click.option(
+    "--min_archive_ratio",
+    type=click.FloatRange(0, 1),
+    default=defaults["min_archive_ratio"],
+    help=f"Minimum allowed compression ratio for an archive. A floating-point value between 0.0 and 1.0, inclusive. Default is {defaults['min_archive_ratio']}",
+)
+@click.version_option(metadata.version("archae"), "-v", "--version")
+def cli(
+    archive_path: str,
+    max_total_size_bytes: int,
+    max_archive_size_bytes: int,
+    min_archive_ratio: float,
+) -> None:
+    """Archae explodes archives."""
+    locate_tools()
+    config["max_total_size_bytes"] = max_total_size_bytes
+    config["max_archive_size_bytes"] = max_archive_size_bytes
+    config["min_archive_ratio"] = min_archive_ratio
+    handle_file(Path(archive_path))
+    debug_print_tracked_files()
+
+
+tracked_files: dict[str, dict] = {}
+base_dir = Path.cwd()
+extract_dir = base_dir / "extracted"
+if extract_dir.exists() and extract_dir.is_dir():
+    shutil.rmtree(extract_dir)
+extract_dir.mkdir(exist_ok=True)
+
+
+def locate_tools() -> None:
+    """Locate external tools."""
+    for cls in archae.util.archiver.BaseArchiver.__subclasses__():
+        tool_path = shutil.which(str(cls.executable_name))
+        if tool_path is not None:
+            tools[str(cls.archiver_name)] = cls(tool_path)  # type: ignore[abstract]
+
+
+def handle_file(file_path: Path) -> None:
+    """Handle a file given its path.
+
+    Args:
+        file_path (Path): The path to the file.
+    """
+    click.echo(f"Starting examination of file: {file_path!s}")
+
+    base_hash = sha256_hash_file(file_path)
+    file_size_bytes = file_path.stat().st_size
+    track_file(base_hash, file_size_bytes)
+    track_file_path(base_hash, file_path)
+    add_metadata_to_hash(base_hash, "type", magic.from_file(file_path))
+    add_metadata_to_hash(base_hash, "type_mime", magic.from_file(file_path, mime=True))
+    extension = file_path.suffix.lstrip(".").lower()
+    add_metadata_to_hash(base_hash, "extension", extension)
+    is_file_archive = is_archive(base_hash)
+    add_metadata_to_hash(base_hash, "is_archive", is_file_archive)
+    if is_file_archive:
+        archiver = get_archiver_for_file(base_hash)
+        if archiver:
+            extracted_size = archiver.get_archive_uncompressed_size(file_path)
+            add_metadata_to_hash(base_hash, "extracted_size", extracted_size)
+            compression_ratio = extracted_size / file_size_bytes
+            add_metadata_to_hash(
+                base_hash, "overall_compression_ratio", compression_ratio
+            )
+            if extracted_size > config["max_archive_size_bytes"]:
+                click.echo(
+                    f"Skipped archive {file_path} because expected size {extracted_size} is greater than max_archive_size_bytes {config['max_archive_size_bytes']}"
+                )
+            elif compression_ratio < config["min_archive_ratio"]:
+                click.echo(
+                    f"Skipped archive {file_path} because compression ratio {compression_ratio:.5f} is less than min_archive_ratio {config['min_archive_ratio']}"
+                )
+            else:
+                extraction_dir = extract_dir / base_hash
+                archiver.extract_archive(file_path, extraction_dir)
+                child_files = list_child_files(extraction_dir)
+                for child_file in child_files:
+                    handle_file(child_file)
+        else:
+            click.echo(f"No suitable archiver found for file: {file_path!s}")
+
+
+def is_archive(hash: str) -> bool:
+    """Determine the appropriate archiver for a file based on its metadata.
+
+    Args:
+        hash (str): The hash of the file.
+
+    Returns:
+        bool: True if the file is an archive, otherwise False.
+
+    """
+    metadata = get_tracked_file_metadata(hash)
+    mime_type = metadata.get("type_mime", "").lower()
+    extension = metadata.get("extension", "").lower()
+
+    for tool in tools.values():
+        if mime_type in tool.mime_types or extension in tool.file_extensions:
+            return True
+
+    return False
+
+
+def get_archiver_for_file(hash: str) -> BaseArchiver | None:
+    """Determine the appropriate archiver for a file based on its metadata.
+
+    Args:
+        hash (str): The hash of the file.
+
+    Returns:
+        str | None: The name of the archiver tool if found, otherwise None.
+    """
+    metadata = get_tracked_file_metadata(hash)
+    mime_type = metadata.get("type_mime", "").lower()
+    extension = metadata.get("extension", "").lower()
+
+    for tool in tools.values():
+        if mime_type in tool.mime_types or extension in tool.file_extensions:
+            return tool
+    return None
+
+
+def list_child_files(directory_path: Path, pattern: str = "*") -> list[Path]:
+    """Recursively get a list of files matching a pattern in a directory.
+
+    Args:
+        directory_path (Path): The starting directory path.
+        pattern (str): The file pattern to match (e.g., '*.txt', '*.py').
+
+    Returns:
+        list: A list of Path objects for the matching files.
+    """
+    # rglob performs a recursive search
+    files = list(directory_path.rglob(pattern))
+    # Optionally, filter out directories if pattern='*'
+    return [file for file in files if file.is_file()]
+
+
+def sha256_hash_file(file_path: Path) -> str:
+    """Computes the SHA-256 hash of a file.
+
+    Args:
+        file_path (Path): The path to the file.
+
+    Returns:
+        str: The SHA-256 hash of the file in hexadecimal format.
+    """
+    try:
+        with file_path.open("rb") as f:
+            # Use hashlib.file_digest for simplicity and efficiency in Python 3.11+
+            digest = hashlib.file_digest(f, "sha256")
+        return digest.hexdigest()
+    except FileNotFoundError:
+        return "Error: File not found"
+
+
+def debug_print_tracked_files() -> None:
+    """Print the tracked files for debugging purposes."""
+    click.echo("------------------------------------------------")
+    for hash, info in tracked_files.items():
+        click.echo(f"Hash: {hash}")
+        click.echo(f"  Size: {info.get('size', 'Unknown')} bytes")
+        for path in info.get("paths", []):
+            click.echo(f"  Path: {path}")
+        click.echo("  Metadata:")
+        for key, value in info.get("metadata", {}).items():
+            click.echo(f"    {key}: {value}")
+
+
+def track_file(hash: str, file_size_bytes: int) -> None:
+    """Track a file by its hash.
+
+    Args:
+        hash (str): The hash of the file to track.
+        file_size_bytes (int): The size of the file in bytes.
+    """
+    if hash not in tracked_files:
+        tracked_files[hash] = {}
+        tracked_files[hash]["size"] = file_size_bytes
+        tracked_files[hash]["metadata"] = {}
+    elif tracked_files[hash]["size"] != file_size_bytes:
+        msg = f"Hash collision detected for hash {hash} with differing sizes."
+        raise RuntimeError(msg)
+
+
+def is_file_tracked(hash: str) -> bool:
+    """Check if a file is tracked by its hash.
+
+    Args:
+        hash (str): The hash of the file to check.
+    """
+    return hash in tracked_files
+
+
+def get_tracked_file_metadata(hash: str) -> dict:
+    """Get metadata for a tracked file by its hash.
+
+    Args:
+        hash (str): The hash of the file.
+
+    Returns:
+        dict: The metadata of the tracked file.
+    """
+    return copy.deepcopy(tracked_files.get(hash, {}).get("metadata", {}))
+
+
+def track_file_path(hash: str, file_path: Path) -> None:
+    """Track a file path by its hash.
+
+    Args:
+        hash (str): The hash of the file.
+        file_path (Path): The path to track.
+    """
+    if "paths" not in tracked_files[hash]:
+        tracked_files[hash]["paths"] = []
+
+    if file_path not in tracked_files[hash]["paths"]:
+        tracked_files[hash]["paths"].append(file_path)
+
+
+def add_metadata_to_hash(hash: str, key: str, value: Any) -> None:
+    """Add metadata to a tracked file.
+
+    Args:
+        hash (str): The hash of the file.
+        key (str): The metadata key.
+        value (Any): The metadata value.
+    """
+    tracked_files[hash]["metadata"][key] = value

archae/util/__init__.py

@@ -0,0 +1 @@
+"""Utility modules for archae."""

archae/util/archiver/__init__.py

@@ -0,0 +1,6 @@
+"""Archiver utilities for extracting archive files."""
+
+from .base_archiver import BaseArchiver
+from .peazip import PeazipArchiver
+from .seven_zip import SevenZipArchiver
+from .unar import UnarArchiver

archae/util/archiver/base_archiver.py

@@ -0,0 +1,55 @@
+"""Base archiver class for extraction tools."""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+
+class BaseArchiver(ABC):
+    """Base class for archiver/extractor tools."""
+
+    @abstractmethod
+    def __init__(self, executable_path: str | Path) -> None:
+        """Initialize the archiver.
+
+        Args:
+            executable_path: Path to the executable.
+        """
+
+    @property
+    def archiver_name(self) -> str:
+        """Get the archiver name."""
+        return self.archiver_name
+
+    @property
+    def executable_name(self) -> str:
+        """Get the executable name."""
+        return self.executable_name
+
+    @property
+    def file_extensions(self) -> list[str]:
+        """A non-abstract method that accesses the class impl for the file extensions."""
+        return self.file_extensions
+
+    @property
+    def mime_types(self) -> list[str]:
+        """A non-abstract method that accesses the class impl for the mime types."""
+        return self.mime_types
+
+    @abstractmethod
+    def extract_archive(self, archive_path: Path, extract_dir: Path) -> None:
+        """Extracts an archive to a specified directory.
+
+        Args:
+            archive_path (Path): The path to the archive file.
+            extract_dir (Path): The directory to extract the archive to.
+
+        """
+
+    @abstractmethod
+    def get_archive_uncompressed_size(self, archive_path: Path) -> int:
+        """Get the uncompressed size of the contents.
+
+        Args:
+            archive_path (Path): The path to the archive file.
+
+        """

archae/util/archiver/peazip.py

@@ -0,0 +1,159 @@
+"""peazip archiver/extractor implementation."""
+
+import subprocess
+from pathlib import Path
+from typing import ClassVar
+
+from .base_archiver import BaseArchiver
+
+
+class PeazipArchiver(BaseArchiver):
+    """Archiver implementation for peazip."""
+
+    file_extensions: ClassVar[list[str]] = [
+        "appinstaller",
+        "appx",
+        "appxbundle",
+        "gz",
+        "tgz",
+        "jar",
+        "ear",
+        "war",
+        "emsix",
+        "emsixbundle",
+        "msix",
+        "msixbundle",
+        "apk",
+        "deb",
+        "cab",
+        "chm",
+        "chw",
+        "chi",
+        "chq",
+        "pptx",
+        "pptm ",
+        "xlsx",
+        "xlsm",
+        "docx",
+        "docm",
+        "7z",
+        "s7z",
+        "ace",
+        "dmg",
+        "img",
+        "arc",
+        "pak",
+        "arj",
+        "br",
+        "bz2",
+        "tbz2",
+        "crx",
+        "z",
+        "taz",
+        "cpio",
+        "arc",
+        "pak",
+        "iso",
+        "img",
+        "lzma",
+        "wim",
+        "swm",
+        "esd",
+        "msi",
+        "msp",
+        "rar",
+        "r00",
+        "rpm",
+        "tar",
+        "vhd",
+        "vhdx",
+        "xar",
+        "pkg",
+        "xpi",
+        "xz",
+        "txz",
+        "ipa",
+        "zip",
+        "zipx",
+        "aar",
+        "zst",
+    ]
+    mime_types: ClassVar[list[str]] = [
+        "application/appinstaller",
+        "application/appx",
+        "application/appxbundle",
+        "application/gzip",
+        "application/java-archive",
+        "application/msix",
+        "application/msixbundle",
+        "application/vnd.android.package-archive",
+        "application/vnd.debian.binary-package",
+        "application/vnd.ms-cab-compressed",
+        "application/vnd.ms-htmlhelp",
+        "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        "application/x-7z-compressed",
+        "application/x-ace-compressed",
+        "application/x-apple-diskimage",
+        "application/x-arc",
+        "application/x-arj",
+        "application/x-brotli",
+        "application/x-bzip2",
+        "application/x-chrome-extension",
+        "application/x-compress",
+        "application/x-cpio",
+        "application/x-freearc",
+        "application/x-iso9660-image",
+        "application/x-lzma",
+        "application/x-ms-wim",
+        "application/x-ole-storage",
+        "application/x-rar-compressed",
+        "application/x-rpm",
+        "application/x-tar",
+        "application/x-vhd",
+        "application/x-xar",
+        "application/x-xpinstall",
+        "application/x-xz",
+        "application/zip",
+        "application/zip",
+        "application/zip",
+        "application/zstd",
+    ]
+    archiver_name: str = "peazip"
+    executable_name: str = "pea"
+
+    def __init__(self, executable_path: str | Path) -> None:
+        """Initialize the peazip archiver.
+
+        Args:
+            executable_path: Path to the peazip executable.
+        """
+        self.executable_path = Path(executable_path)
+
+    def extract_archive(self, archive_path: Path, extract_dir: Path) -> None:
+        """Extracts an archive to a specified directory.
+
+        Args:
+            archive_path (Path): The path to the archive file.
+            extract_dir (Path): The directory to extract the archive to.
+
+        """
+        command: list[str] = [
+            str(self.executable_path),
+            "-ext2simple",
+            str(archive_path),
+            str(extract_dir),
+        ]
+        subprocess.run(command, check=True)  # noqa: S603
+
+    def get_archive_uncompressed_size(self, archive_path: Path) -> int:  # noqa: ARG002
+        """Get the uncompressed size of the contents.
+
+        Args:
+            archive_path (Path): The path to the archive file.
+
+        Returns:
+            int: The size of the contents
+        """
+        return -1

archae/util/archiver/seven_zip.py

@@ -0,0 +1,199 @@
+"""7zip archiver/extractor implementation."""
+
+import subprocess
+from pathlib import Path
+from typing import ClassVar
+
+from .base_archiver import BaseArchiver
+
+
+class SevenZipArchiver(BaseArchiver):
+    """Archiver implementation for 7zip."""
+
+    file_extensions: ClassVar[list[str]] = [
+        "7z",
+        "s7z",
+        "apk",
+        "bz2",
+        "tbz2",
+        "crx",
+        "xpi",
+        "deb",
+        "gz",
+        "tgz",
+        "ipa",
+        "jar",
+        "ear",
+        "war",
+        "lzma",
+        "cab",
+        "docx",
+        "docm",
+        "pptx",
+        "pptm",
+        "xlsx",
+        "xlsm",
+        "emsix",
+        "emsixbundle",
+        "msix",
+        "appinstaller",
+        "appx",
+        "appxbundle",
+        "msixbundle",
+        "z",
+        "taz",
+        "tar",
+        "zip",
+        "zipx",
+        "appimage",
+        "dmg ",
+        "img",
+        "arj",
+        "cpio",
+        "cramfs",
+        "raw",
+        "alz",
+        "ext",
+        "ext2",
+        "ext3",
+        "ext4",
+        "xar",
+        "pkg",
+        "fat",
+        "gpt",
+        "hfs",
+        "hfsx",
+        "iso",
+        "lha",
+        "lhz",
+        "mbr",
+        "chm",
+        "chw",
+        "chi",
+        "chq",
+        "msi",
+        "msp",
+        "vhd",
+        "vhdx",
+        "ntfs",
+        "nsi",
+        "exe",
+        "nsis",
+        "qcow2",
+        "qcow",
+        "qcow2c",
+        "rpm",
+        "rar",
+        "r00",
+        "sqfs",
+        "sfs",
+        "sqsh",
+        "squashfs",
+        "scap",
+        "uefif",
+        "udf",
+        "edb",
+        "edp",
+        "edr",
+        "a",
+        "ar",
+        "deb",
+        "lib",
+        "vdi",
+        "vmdk",
+        "wim",
+        "swm",
+        "esd",
+        "xz",
+        "txz",
+    ]
+    mime_types: ClassVar[list[str]] = [
+        "application/x-7z-compressed",
+        "application/vnd.android.package-archive",
+        "application/x-bzip2",
+        "application/x-chrome-extension",
+        "application/x-xpinstall",
+        "application/vnd.debian.binary-package",
+        "application/gzip",
+        "application/java-archive",
+        "application/x-lzma",
+        "application/vnd.ms-cab-compressed",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        "application/msix",
+        "application/appinstaller",
+        "application/appx",
+        "application/appxbundle",
+        "application/msixbundle",
+        "application/x-compress",
+        "application/x-tar",
+        "application/zip",
+        "application/x-apple-diskimage",
+        "application/x-arj",
+        "application/x-cpio",
+        "application/vnd.efi.img",
+        "application/x-alz-compressed",
+        "application/x-xar",
+        "application/x-iso9660-image",
+        "application/x-lzh",
+        "application/vnd.ms-htmlhelp",
+        "application/x-ole-storage",
+        "application/x-vhd",
+        "text/x-nsis",
+        "application/x-qemu-disk",
+        "application/x-rpm",
+        "application/x-rar-compressed",
+        "application/vnd.squashfs",
+        "application/x-archive",
+        "application/x-virtualbox-vdi",
+        "application/x-vmdk-disk",
+        "application/x-ms-wim",
+        "application/x-xz",
+    ]
+    archiver_name: str = "7zip"
+    executable_name: str = "7z"
+
+    def __init__(self, executable_path: str | Path) -> None:
+        """Initialize the 7zip archiver.
+
+        Args:
+            executable_path: Path to the 7zip executable.
+        """
+        self.executable_path = Path(executable_path)
+
+    def extract_archive(self, archive_path: Path, extract_dir: Path) -> None:
+        """Extracts an archive to a specified directory.
+
+        Args:
+            archive_path (Path): The path to the archive file.
+            extract_dir (Path): The directory to extract the archive to.
+
+        """
+        command: list[str] = [
+            str(self.executable_path),
+            "x",
+            str(archive_path),
+            f"-o{extract_dir!s}",
+        ]
+        subprocess.run(command, check=True)  # noqa: S603
+
+    def get_archive_uncompressed_size(self, archive_path: Path) -> int:
+        """Get the uncompressed size of the contents.
+
+        Args:
+            archive_path (Path): The path to the archive file.
+
+        Returns:
+            int: The size of the contents
+        """
+        command: list[str] = [str(self.executable_path), "l", "-slt", str(archive_path)]
+        result = subprocess.run(command, check=True, capture_output=True, text=True)  # noqa: S603
+
+        result_lines = str(result.stdout).splitlines()
+        exploded_size = 0
+        for line in result_lines:
+            if line.startswith("Size = "):
+                exploded_size += int(line[7:])
+
+        return exploded_size

archae/util/archiver/unar.py

@@ -0,0 +1,158 @@
+"""unar archiver/extractor implementation."""
+
+import subprocess
+from pathlib import Path
+from typing import ClassVar
+
+from .base_archiver import BaseArchiver
+
+
+class UnarArchiver(BaseArchiver):
+    """Archiver implementation for unar."""
+
+    file_extensions: ClassVar[list[str]] = [
+        "appinstaller",
+        "appx",
+        "appxbundle",
+        "gz",
+        "tgz",
+        "emsix",
+        "emsixbundle",
+        "msix",
+        "msixbundle",
+        "apk",
+        "deb",
+        "cab",
+        "pptx",
+        "pptm ",
+        "xlsx ",
+        "xlsm",
+        "docx",
+        "docm",
+        "7z",
+        "s7z",
+        "ace",
+        "alz",
+        "arc",
+        "pak",
+        "a",
+        "ar",
+        "deb",
+        "lib",
+        "arj",
+        "bz2",
+        "tbz2",
+        "crx",
+        "z",
+        "taz",
+        "cpio",
+        "arc",
+        "pak",
+        "iso",
+        "img",
+        "lha",
+        "lhz",
+        "lzma",
+        "msi",
+        "msp",
+        "rar",
+        "r00",
+        "sit",
+        "sitx",
+        "tar",
+        "xar",
+        "pkg",
+        "xpi",
+        "xz",
+        "txz",
+        "zoo",
+        "zip",
+        "zipx",
+        "aar",
+        "nsi",
+        "exe",
+        "nsis",
+        "udf",
+        "edb",
+        "edp",
+        "edr",
+    ]
+    mime_types: ClassVar[list[str]] = [
+        "application/appinstaller",
+        "application/appx",
+        "application/appxbundle",
+        "application/gzip",
+        "application/msix",
+        "application/msixbundle",
+        "application/vnd.android.package-archive",
+        "application/vnd.debian.binary-package",
+        "application/vnd.ms-cab-compressed",
+        "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        "application/x-7z-compressed",
+        "application/x-ace-compressed",
+        "application/x-alz-compressed",
+        "application/x-arc",
+        "application/x-archive",
+        "application/x-arj",
+        "application/x-bzip2",
+        "application/x-chrome-extension",
+        "application/x-compress",
+        "application/x-cpio",
+        "application/x-freearc",
+        "application/x-iso9660-image",
+        "application/x-lzh",
+        "application/x-lzma",
+        "application/x-ole-storage",
+        "application/x-rar-compressed",
+        "application/x-stuffit",
+        "application/x-sit",
+        "application/x-stuffitx",
+        "application/x-sitx",
+        "application/x-tar",
+        "application/x-xar",
+        "application/x-xpinstall",
+        "application/x-xz",
+        "application/x-zoo",
+        "application/zip",
+        "application/zip",
+        "text/x-nsis",
+    ]
+    archiver_name: str = "unar"
+    executable_name: str = "unar"
+
+    def __init__(self, executable_path: str | Path) -> None:
+        """Initialize the unar archiver.
+
+        Args:
+            executable_path: Path to the unar executable.
+        """
+        self.executable_path = Path(executable_path)
+
+    def extract_archive(self, archive_path: Path, extract_dir: Path) -> None:
+        """Extracts an archive to a specified directory.
+
+        Args:
+            archive_path (Path): The path to the archive file.
+            extract_dir (Path): The directory to extract the archive to.
+
+        """
+        command: list[str] = [
+            str(self.executable_path),
+            "-o",
+            str(extract_dir),
+            str(archive_path),
+        ]
+        subprocess.run(command, check=True)  # noqa: S603
+
+    def get_archive_uncompressed_size(self, archive_path: Path) -> int:  # noqa: ARG002
+        """Get the uncompressed size of the contents.
+
+        Args:
+            archive_path (Path): The path to the archive file.
+
+        Returns:
+            int: The size of the contents
+        """
+        return -1

archae/util/enum/__init__.py

@@ -0,0 +1,5 @@
+"""Enum utilities for archae."""
+
+from archae.util.enum.byte_scale import ByteScale
+
+__all__ = ["ByteScale"]

archae/util/enum/byte_scale.py

@@ -0,0 +1,46 @@
+"""Byte scale enum for file size operations."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Self
+
+
+class ByteScale(Enum):
+    """Byte scale prefix converter."""
+
+    NONE = (0, "")
+    KILO = (1, "K")
+    MEGA = (2, "M")
+    GIGA = (3, "G")
+    TERA = (4, "T")
+    PETA = (5, "P")
+
+    def __new__(cls, exponent: int, prefix_letter: str) -> Self:
+        """Apply values to the new Enum.
+
+        __new__ is used to control how new enum members are instantiated.
+        It must set the `_value_` attribute and any custom attributes.
+
+        Args:
+            exponent (int): the exponent value for the scale
+            prefix_letter (str): the prefix letter for the scale
+
+        Returns:
+            ByteScale: A new ByteScale enum.
+
+        """
+        obj = object.__new__(cls)
+        obj._value_ = exponent
+        obj.prefix_letter = prefix_letter
+        return obj
+
+    @property
+    def prefix_letter(self) -> str:
+        """Return the prefix letter for this scale."""
+        return self._prefix_letter
+
+    @prefix_letter.setter
+    def prefix_letter(self, value: str) -> None:
+        """Setter for prefix letter."""
+        self._prefix_letter = value

archae-2026.1.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.3
+Name: archae
+Version: 2026.1.0
+Summary: Archae explodes archives.
+Keywords: 
+Author: Shawn McNaughton
+Author-email: Shawn McNaughton <shawngmc@gmail.com>
+License: MIT License
+         
+         Copyright © 2026 Shawn McNaughton
+         
+         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.
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Dist: click
+Requires-Dist: python-magic
+Requires-Dist: rich-click
+Requires-Python: ~=3.11
+Project-URL: Documentation, https://archae.readthedocs.io/en/stable/
+Project-URL: Changelog, https://archae.readthedocs.io/en/stable/changelog.html
+Project-URL: Source Code, https://github.com/shawngmc/archae
+Project-URL: Issue Tracker, https://github.com/shawngmc/archae/issues
+Description-Content-Type: text/markdown
+
+<!-- start docs-include-index -->
+
+# Archae
+
+![Archae Logo of a spider exploring a sarcophagus](./_static/archae_logo.png)
+
+[![PyPI](https://img.shields.io/pypi/v/archae)](https://img.shields.io/pypi/v/archae)
+[![Supported Python Versions](https://img.shields.io/pypi/pyversions/archae)](https://pypi.org/project/archae/)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/shawngmc/archae/main.svg)](https://results.pre-commit.ci/latest/github/shawngmc/archae/main)
+[![Test](https://github.com/shawngmc/archae/actions/workflows/test.yml/badge.svg)](https://github.com/shawngmc/archae/actions/workflows/test.yml)
+[![Documentation Status](https://readthedocs.org/projects/archae/badge/?version=latest)](https://archae.readthedocs.io/en/latest/?badge=latest)
+[![PyPI - License](https://img.shields.io/pypi/l/archae)](https://img.shields.io/pypi/l/archae)
+
+Archae explodes archives.
+
+<!-- end docs-include-index -->
+
+## Installation
+
+<!-- start docs-include-installation -->
+
+Archae is available on [PyPI](https://pypi.org/project/archae/). Install with [uv](https://docs.astral.sh/uv/) or your package manager of choice:
+
+```sh
+uv tool install archae
+```
+
+<!-- end docs-include-installation -->
+
+## Documentation
+
+Check out the [Archae documentation](https://archae.readthedocs.io/en/stable/) for the [User's Guide](https://archae.readthedocs.io/en/stable/usage.html) and [CLI Reference](https://archae.readthedocs.io/en/stable/cli.html).
+
+## Usage
+
+<!-- start docs-include-usage -->
+
+Running `archae --help` or `python -m archae --help` shows a list of all of the available options and arguments:
+
+<!-- [[[cog
+import cog
+from archae import cli
+from click.testing import CliRunner
+runner = CliRunner()
+result = runner.invoke(cli.cli, ["--help"], terminal_width=88)
+help = result.output.replace("Usage: cli", "Usage: archae")
+cog.outl(f"\n```sh\narchae --help\n{help.rstrip()}\n```\n")
+]]] -->
+
+```sh
+archae --help
+
+ Usage: archae [OPTIONS] ARCHIVE_PATH
+
+ Archae explodes archives.
+
+╭─ Arguments ──────────────────────────────────────────────────────────────────────────╮
+│ *  ARCHIVE_PATH  FILE  Archive to examine [required]                                 │
+╰──────────────────────────────────────────────────────────────────────────────────────╯
+╭─ Options ────────────────────────────────────────────────────────────────────────────╮
+│ --max_total_size_bytes        FILESIZE               Maximum total extraction size   │
+│                                                      before failing, default 100G    │
+│                                                      [default: 107374182400]         │
+│ --max_archive_size_bytes      FILESIZE               Maximum individual archive      │
+│                                                      extraction size before failing, │
+│                                                      default 10G [default:           │
+│                                                      10737418240]                    │
+│ --min_archive_ratio           FLOAT RANGE [0<=x<=1]  Minimum allowed compression     │
+│                                                      ratio for an archive. A         │
+│                                                      floating-point value between    │
+│                                                      0.0 and 1.0, inclusive. Default │
+│                                                      is 0.005 [default: 0.005]       │
+│ --version                 -v                         Show the version and exit.      │
+│ --help                    -h                         Show this message and exit.     │
+╰──────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+<!-- [[[end]]] -->
+
+<!-- end docs-include-usage -->
+
+## Features
+
+- Uses 7z/peazip/unar (not 7za/7zr) to try to extract archives
+- No substantial limit on the number of archive layers
+- Identifies file types via libmagic
+- Basic archive bomb protections
+
+## TODOs
+
+- Protect against/detect archive bombs (malicious disk usage)
+- Improve archive type detection
+- Separate between extractable and non-extractable archive types
+- Protect against/detect depth attacks (excessively nested archives)
+- Detect password-protected archives
+- Allow supplying archive passwords by hash
+- Add custom magic to detect obscure archive formats

archae-2026.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+archae/__init__.py,sha256=tqGdU1tlaD9BIf9_PfhiMRLVsoqTTHr9JIJq7jht1ys,32
+archae/__main__.py,sha256=l3eO5dEs1cR_hDziOpnW1PYzoRL2siYm81wgvftyigg,172
+archae/cli.py,sha256=lmkoCa_G-OV1UvdvvpNwbwgr9c1LdZNfEsZjrGXvAOY,11949
+archae/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+archae/util/__init__.py,sha256=HlENK1XfnwnYMrlkvVJTjs-6W7RLLUJOoyFcOb7njUE,34
+archae/util/archiver/__init__.py,sha256=baayr_wh2MfRaKKiVuaUxtYJcMzKR82Uf1amcU7QtzM,202
+archae/util/archiver/base_archiver.py,sha256=_2-ARZLxPqSeE_0TF7NTVK8TwWhLyP9fA2G0fnMb0zc,1549
+archae/util/archiver/peazip.py,sha256=XdhI2EQ3A9EH89KxPv-FcmjukwWcS96WtG-gwkha6hs,4022
+archae/util/archiver/seven_zip.py,sha256=eck_cXMGFqwJ05ZKge3N0Ozy1XkKuGyE09s3jFcsMrQ,4951
+archae/util/archiver/unar.py,sha256=xWTR7cpFXyofvtPI-7Z5Ski605WmJdLoAm6a81IriAc,3974
+archae/util/enum/__init__.py,sha256=IvjtVopATKLAHDjOpblaExy2yXwIzweX0HoUrQWcpkM,109
+archae/util/enum/byte_scale.py,sha256=uCTTaT0hiDKdVwJ1l6i35_Iv2VVpHmnW9i0gfZ5FB1I,1204
+archae-2026.1.0.dist-info/WHEEL,sha256=fAguSjoiATBe7TNBkJwOjyL1Tt4wwiaQGtNtjRPNMQA,80
+archae-2026.1.0.dist-info/entry_points.txt,sha256=gGL_R78QELaTeyFGb-OuSnRuu4EUdT68EKmyrFno59o,48
+archae-2026.1.0.dist-info/METADATA,sha256=UJAYwbNwo-bwsddem7zknCuJ4Q0xbFinjfgpqA2CEt0,7457
+archae-2026.1.0.dist-info/RECORD,,

archae-2026.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.28
+Root-Is-Purelib: true
+Tag: py3-none-any

archae-2026.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+archae = archae.__main__:cli
+