archae 2026.2.0__py3-none-any.whl

archae/__init__.py

@@ -0,0 +1,5 @@
+"""Archae explodes archives."""
+
+from archae.extractor import ArchiveExtractor
+
+__all__ = ["ArchiveExtractor"]

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,176 @@
+"""Main CLI for archae."""
+
+from __future__ import annotations
+
+import logging
+import pathlib
+from importlib import metadata
+from pathlib import Path
+
+import rich_click as click
+
+from archae.config import apply_options, convert_settings, get_options
+from archae.extractor import ArchiveExtractor
+from archae.util.tool_manager import ToolManager
+
+logger = logging.getLogger("archae")
+logger.setLevel(logging.INFO)
+
+
+@click.group(
+    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.version_option(metadata.version("archae"), "-v", "--version")
+def cli() -> None:
+    """Archae explodes archives."""
+
+
+@cli.command()
+@click.argument(
+    "archive_path",
+    type=click.Path(exists=True, dir_okay=False, readable=True, path_type=pathlib.Path),
+    default=Path.cwd() / "extracted",
+    help="Archive to examine",
+)
+@click.option(
+    "-o",
+    "--opt",
+    "options",
+    nargs=2,
+    type=click.Tuple([str, str]),
+    multiple=True,
+    help="Set config options as key value pairs. Use 'archae listopts' to see available options.",
+)
+@click.option(
+    "-e",
+    "--extract-dir",
+    "extract_dir",
+    nargs=1,
+    type=click.Path(
+        dir_okay=True,
+        file_okay=False,
+        readable=True,
+        writable=True,
+        path_type=pathlib.Path,
+    ),
+    default=Path.cwd() / "extracted",
+    help="Set config options as key value pairs. Use 'archae listopts' to see available options.",
+)
+def extract(
+    archive_path: pathlib.Path,
+    options: list[tuple[str, str]] | None,
+    extract_dir: pathlib.Path,
+) -> None:
+    """Extract and analyze an archive."""
+    # Apply any options from the command line, then convert any convertible settings
+    if options:
+        apply_options(options)
+    convert_settings()
+
+    # Locate external tools
+    ToolManager.locate_tools()
+    extractor = ArchiveExtractor(extract_dir=extract_dir)
+    extractor.handle_file(archive_path)
+    print_tracked_files(extractor.get_tracked_files())
+    print_warnings(extractor.get_warnings())
+
+
+@cli.command()
+def listopts() -> None:
+    """List all available configuration options."""
+    options = get_options()
+
+    # Load default settings
+    defaults_path = Path(__file__).parent / "default_settings.toml"
+    defaults_content = defaults_path.read_text()
+    defaults = {}
+    in_default_section = False
+    for line in defaults_content.split("\n"):
+        if line.strip() == "[default]":
+            in_default_section = True
+            continue
+        if in_default_section and line.startswith("["):
+            break
+        if in_default_section and "=" in line:
+            key, value = line.split("=", 1)
+            defaults[key.strip()] = value.strip().strip('"')
+
+    logger.info("Available configuration options:")
+    logger.info("------------------------------------------------")
+    for option_name, option_def in sorted(options.items()):
+        logger.info("%s (%s)", option_name, option_def.get("type", "unknown"))
+        logger.info("  %s", option_def.get("help", "No description available"))
+        if option_name in defaults:
+            logger.info("  Default: %s", defaults[option_name])
+
+
+@cli.command()
+def status() -> None:
+    """Show archae status and available tools."""
+    logger.info("Archae status:")
+    logger.info("Version: %s", metadata.version("archae"))
+    ToolManager.locate_tools()
+    logger.info("Tools located and ready to use.")
+    logger.info("------------------------------------------------")
+
+    # Show supported extensions
+    supported_ext = ToolManager.get_supported_extensions()
+    logger.info("Supported file extensions (%d):", len(supported_ext))
+    if supported_ext:
+        logger.info("  %s", ", ".join(supported_ext))
+    else:
+        logger.info("  (none)")
+
+    # Show unsupported extensions
+    unsupported_ext = ToolManager.get_unsupported_extensions()
+    logger.info("Unsupported file extensions (%d):", len(unsupported_ext))
+    if unsupported_ext:
+        logger.info("  %s", ", ".join(unsupported_ext))
+    else:
+        logger.info("  (none)")
+
+    logger.info("------------------------------------------------")
+
+    # Show supported MIME types
+    supported_mime = ToolManager.get_supported_mime_types()
+    logger.info("Supported MIME types (%d):", len(supported_mime))
+    if supported_mime:
+        logger.info("  %s", ", ".join(supported_mime))
+    else:
+        logger.info("  (none)")
+
+    # Show unsupported MIME types
+    unsupported_mime = ToolManager.get_unsupported_mime_types()
+    logger.info("Unsupported MIME types (%d):", len(unsupported_mime))
+    if unsupported_mime:
+        logger.info("  %s", ", ".join(unsupported_mime))
+    else:
+        logger.info("  (none)")
+
+
+def print_tracked_files(tracked_files: dict[str, dict]) -> None:
+    """Print the tracked files for debugging purposes."""
+    logger.info("------------------------------------------------")
+    for hash, info in tracked_files.items():
+        logger.info("Hash: %s", hash)
+        logger.info("  Size: %s bytes", info.get("size", "Unknown"))
+        for path in info.get("paths", []):
+            logger.info("  Path: %s", path)
+        logger.info("  Metadata:")
+        for key, value in info.get("metadata", {}).items():
+            logger.info("    %s: %s", key, value)
+
+
+def print_warnings(warnings: list[str]) -> None:
+    """Print accumulated warnings for debugging purposes."""
+    logger.info("------------------------------------------------")
+    logger.info("Accumulated Warnings:")
+    for warning in warnings:  # type: ignore[attr-defined]
+        logger.info(warning)

archae/config.py

@@ -0,0 +1,107 @@
+"""Runtime config management (default, userconfig and envvars)."""
+
+import importlib
+import typing
+from pathlib import Path
+
+import platformdirs
+import yaml
+from dynaconf import Dynaconf
+
+# Get the package directory for default settings
+package_dir = Path(__file__).parent
+default_settings_file = package_dir / "default_settings.toml"
+
+# Get the config directory following XDG standards
+config_dir = Path(platformdirs.user_config_dir("archae"))
+config_dir.mkdir(parents=True, exist_ok=True)
+
+# Define the user config file path
+user_config_file = config_dir / "settings.toml"
+
+# Create a default settings.toml if it doesn't exist
+if not user_config_file.exists():
+    user_config_file.write_text("""# Archae configuration
+# Override defaults from the package here
+""")
+
+settings = Dynaconf(
+    envvar_prefix="ARCHAE",
+    settings_files=[
+        str(default_settings_file),  # Load package defaults first
+        str(user_config_file),  # User settings override defaults
+    ],
+    environments=True,
+)
+
+default_settings = Dynaconf(
+    envvar_prefix="ARCHAE",
+    settings_files=[
+        str(default_settings_file),  # Load package defaults first
+    ],
+    environments=True,
+)
+
+
+options_file = package_dir / "options.yaml"
+
+
+def get_options() -> dict:
+    """Return the contents of options.yaml."""
+    with Path.open(options_file) as f:
+        return yaml.safe_load(f)
+
+
+def get_converter(converter_def: str) -> typing.Callable:
+    """Dynamically import and instantiate a converter class.
+
+    Args:
+        converter_def (str): Converter definition in format "module.path:ClassName" or a builtin type like "float" or "int".
+
+    Returns:
+        Converter function.
+    """
+    # Handle built-in types
+    if converter_def == "float":
+        return float
+    if converter_def == "int":
+        return int
+
+    # Split the definition into module path and class name
+    module_name, class_name = converter_def.split(":")
+
+    # Import the module
+    module = importlib.import_module(module_name)
+
+    # Get the class from the module
+    return getattr(module, class_name)
+
+
+def apply_options(option_list: list[tuple[str, str]]) -> None:
+    """Apply a list of options to the settings.
+
+    Args:
+        option_list (list[tuple[str, str]]): List of key-value pairs to apply.
+
+    """
+    options = get_options()
+    for key, value in option_list:
+        # Find the option definition by matching the key
+        option_def = None
+        for def_key in options:
+            option_def = options[def_key]
+            break
+        if option_def:
+            settings[key] = value
+        else:
+            pass
+
+
+def convert_settings() -> None:
+    """Convert settings using their defined converters."""
+    options = get_options()
+    for key in options:
+        option_def = options[key]
+        if "converter" in option_def:
+            converter = get_converter(option_def["converter"])
+            settings[key] = converter(settings[key])

archae/default_settings.toml

@@ -0,0 +1,9 @@
+# Default archae configuration
+# Users can override these in ~/.config/archae/settings.toml
+
+[default]
+MAX_TOTAL_SIZE_BYTES = "100G"
+MAX_ARCHIVE_SIZE_BYTES = "10G"
+MIN_ARCHIVE_RATIO = 0.005
+MIN_DISK_FREE_SPACE = "10G"
+MAX_DEPTH=0

archae/extractor.py

@@ -0,0 +1,249 @@
+"""Archive extraction module for archae."""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import shutil
+from typing import TYPE_CHECKING
+
+import magic
+
+from archae.config import apply_options, default_settings, settings
+from archae.util.file_tracker import FileTracker
+from archae.util.tool_manager import ToolManager
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from archae.util.archiver.base_archiver import BaseArchiver
+
+
+class WarningAccumulator(logging.Handler):
+    """Logging handler to accumulate warnings while still printing them."""
+
+    def __init__(self) -> None:
+        """Initialize the WarningAccumulator."""
+        super().__init__()
+        self.warnings: list[str] = []
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Print and accumulate warning messages."""
+        if record.levelno >= logging.WARNING:
+            self.warnings.append(self.format(record))
+        print(self.format(record))  # noqa: T201
+
+
+logger = logging.getLogger("archae")
+logger.setLevel(logging.INFO)
+accumulator = WarningAccumulator()
+logger.addHandler(accumulator)
+logger.setLevel(logging.DEBUG)
+
+
+class ArchiveExtractor:
+    """Handles archive extraction and file tracking."""
+
+    def __init__(self, extract_dir: Path) -> None:
+        """Initialize the ArchiveExtractor.
+
+        Args:
+            extract_dir (Path): The base directory for extraction. Defaults to current working directory + extracted.
+        """
+        self.extract_dir = extract_dir
+        if self.extract_dir.exists() and self.extract_dir.is_dir():
+            shutil.rmtree(self.extract_dir)
+        self.extract_dir.mkdir(exist_ok=True)
+        self.file_tracker = FileTracker()
+
+    def handle_file(self, file_path: Path) -> None:
+        """Handle a file given its path.
+
+        Args:
+            file_path (Path): The path to the file.
+        """
+        self.__handle_file(file_path)
+
+    def __handle_file(self, file_path: Path, depth: int = 1) -> None:
+        """Internal implementation of handle_file.
+
+        Args:
+            file_path (Path): The path to the file.
+            depth (int): The current depth in the archive extraction tree. Defaults to 1.
+        """
+        logger.info("Starting examination of file: %s", file_path)
+
+        base_hash = self._sha256_hash_file(file_path)
+        file_size_bytes = file_path.stat().st_size
+        self.file_tracker.track_file(base_hash, file_size_bytes)
+        self.file_tracker.track_file_path(base_hash, file_path)
+        self.file_tracker.add_metadata_to_hash(
+            base_hash, "type", magic.from_file(file_path)
+        )
+        self.file_tracker.add_metadata_to_hash(
+            base_hash, "type_mime", magic.from_file(file_path, mime=True)
+        )
+        extension = file_path.suffix.lstrip(".").lower()
+        self.file_tracker.add_metadata_to_hash(base_hash, "extension", extension)
+        is_file_archive = self._is_archive(base_hash)
+        self.file_tracker.add_metadata_to_hash(base_hash, "is_archive", is_file_archive)
+        if is_file_archive:
+            if settings["MAX_DEPTH"] == 0 or depth < settings["MAX_DEPTH"]:
+                archiver = self._get_archiver_for_file(base_hash)
+                if archiver:
+                    extracted_size = archiver.get_archive_uncompressed_size(file_path)
+                    self.file_tracker.add_metadata_to_hash(
+                        base_hash, "extracted_size", extracted_size
+                    )
+                    compression_ratio = extracted_size / file_size_bytes
+                    self.file_tracker.add_metadata_to_hash(
+                        base_hash, "overall_compression_ratio", compression_ratio
+                    )
+                    if extracted_size > settings["MAX_ARCHIVE_SIZE_BYTES"]:
+                        logger.warning(
+                            "MAX_ARCHIVE_SIZE_BYTES: Skipped archive %s because expected size %s is greater than MAX_ARCHIVE_SIZE_BYTES %s",
+                            file_path,
+                            extracted_size,
+                            settings["MAX_ARCHIVE_SIZE_BYTES"],
+                        )
+                    elif (
+                        self.file_tracker.get_tracked_file_size() + extracted_size
+                        > settings["MAX_TOTAL_SIZE_BYTES"]
+                    ):
+                        logger.warning(
+                            "MAX_TOTAL_SIZE_BYTES: Skipped archive %s because expected size %s + current tracked files %s is greater than MAX_TOTAL_SIZE_BYTES %s",
+                            file_path,
+                            extracted_size,
+                            self.file_tracker.get_tracked_file_size(),
+                            settings["MAX_TOTAL_SIZE_BYTES"],
+                        )
+                    elif compression_ratio < settings["MIN_ARCHIVE_RATIO"]:
+                        logger.warning(
+                            "MIN_ARCHIVE_RATIO: Skipped archive %s because compression ratio %.5f is less than MIN_ARCHIVE_RATIO %s",
+                            file_path,
+                            compression_ratio,
+                            settings["MIN_ARCHIVE_RATIO"],
+                        )
+                    elif (
+                        shutil.disk_usage(self.extract_dir).free - extracted_size
+                        < settings["MIN_DISK_FREE_SPACE"]
+                    ):
+                        logger.warning(
+                            "MIN_DISK_FREE_SPACE:Skipped archive %s because extracting it would leave less than MIN_DISK_FREE_SPACE %s bytes free at extraction location %s",
+                            file_path,
+                            settings["MIN_DISK_FREE_SPACE"],
+                            self.extract_dir,
+                        )
+                    else:
+                        extraction_dir = self.extract_dir / base_hash
+                        archiver.extract_archive(file_path, extraction_dir)
+                        child_files = self._list_child_files(extraction_dir)
+                        for child_file in child_files:
+                            self.__handle_file(child_file, depth + 1)
+                else:
+                    logger.warning(
+                        "NO_ARCHIVER: No suitable archiver found for file: %s",
+                        file_path,
+                    )
+            else:
+                logger.warning(
+                    "MAX_DEPTH: File %s is not extracted; max depth reached.", file_path
+                )
+
+    def _is_archive(self, file_hash: str) -> bool:
+        """Determine the appropriate archiver for a file based on its metadata.
+
+        Args:
+            file_hash (str): The hash of the file.
+
+        Returns:
+            bool: True if the file is an archive, otherwise False.
+
+        """
+        metadata = self.file_tracker.get_tracked_file_metadata(file_hash)
+        mime_type = metadata.get("type_mime", "").lower()
+        extension = metadata.get("extension", "").lower()
+
+        for tool in ToolManager.get_tools().values():
+            if mime_type in tool.mime_types or extension in tool.file_extensions:
+                return True
+
+        return False
+
+    def _get_archiver_for_file(self, file_hash: str) -> BaseArchiver | None:
+        """Determine the appropriate archiver for a file based on its metadata.
+
+        Args:
+            file_hash (str): The hash of the file.
+
+        Returns:
+            str | None: The name of the archiver tool if found, otherwise None.
+        """
+        metadata = self.file_tracker.get_tracked_file_metadata(file_hash)
+        mime_type = metadata.get("type_mime", "").lower()
+        extension = metadata.get("extension", "").lower()
+
+        for tool in ToolManager.get_tools().values():
+            if mime_type in tool.mime_types or extension in tool.file_extensions:
+                return tool
+        return None
+
+    @staticmethod
+    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()]
+
+    @staticmethod
+    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:
+                digest = hashlib.file_digest(f, "sha256")
+            return digest.hexdigest()
+        except FileNotFoundError:
+            return "Error: File not found"
+
+    def get_tracked_files(self) -> dict[str, dict]:
+        """Print the tracked files for debugging purposes."""
+        return self.file_tracker.get_tracked_files()
+
+    def get_warnings(self) -> list[str]:
+        """Print accumulated warnings for debugging purposes."""
+        return accumulator.warnings
+
+    def get_default_settings(self) -> dict:
+        """Get the default settings from the config module.
+
+        Returns:
+            dict: Dictionary of default settings.
+        """
+        return dict(default_settings)
+
+    def apply_settings(self, option_list: list[tuple[str, str]]) -> None:
+        """Apply a list of settings options.
+
+        Args:
+            option_list (list[tuple[str, str]]): List of (key, value) tuples to apply.
+
+        Example:
+            extractor.apply_settings([("MAX_ARCHIVE_SIZE_BYTES", "5000000000")])
+        """
+        apply_options(option_list)

archae/options.yaml

@@ -0,0 +1,39 @@
+MAX_TOTAL_SIZE_BYTES:
+  type: int
+  converter: archae.util.converter.file_size:convert
+  help: Maximum total size of all archives to extract in bytes.
+  examples:
+    - 1GB
+    - 500M
+    - 500
+MAX_ARCHIVE_SIZE_BYTES:
+  type: int
+  converter: archae.util.converter.file_size:convert
+  help: Maximum size of a single archive to extract in bytes.
+  examples:
+    - 1GB
+    - 500M
+    - 500
+MIN_ARCHIVE_RATIO:
+  type: float
+  converter: float
+  help: Minimum compression ratio (compressed size / uncompressed size) required to extract an archive.
+  examples:
+    - 0.001
+MIN_DISK_FREE_SPACE:
+  type: int
+  converter: archae.util.converter.file_size:convert
+  help: Minimum required estimated disk space after extraction in bytes.
+  examples:
+    - 1GB
+    - 500M
+    - 500
+MAX_DEPTH:
+  type: int
+  converter: int
+  help: Maximum extraction depth for nested archives. Usse 0 for unlimited depth.
+  examples:
+    - 3
+    - 5
+    - 10
+    - 0

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.__class__.file_extensions  # type: ignore[return-value]
+
+    @property
+    def mime_types(self) -> list[str]:
+        """A non-abstract method that accesses the class impl for the mime types."""
+        return self.__class__.mime_types  # type: ignore[return-value]
+
+    @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.
+
+        """