archae 2026.1.0b2__py3-none-any.whl → 2026.2.0b1__py3-none-any.whl

archae/__init__.py

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

archae/cli.py

@@ -2,111 +2,22 @@
 
 from __future__ import annotations
 
-import copy
-import hashlib
-import re
-import shutil
+import logging
+import pathlib
 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
+from archae.config import apply_options, convert_settings, get_options
+from archae.extractor import ArchiveExtractor
+from archae.util.tool_manager import ToolManager
 
-if TYPE_CHECKING:
-    from archae.util.archiver.base_archiver import BaseArchiver
+logger = logging.getLogger("archae")
+logger.setLevel(logging.INFO)
 
-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*([KMGTP]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[0].upper()
-
-        byte_scale = 1024 ** (ByteScale.from_prefix_letter(unit).value)
-
-        # Default to bytes if no specific unit multiplier, or assume B
-        return int(number * byte_scale)
-
-    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(
+@click.group(
     context_settings={"help_option_names": ["-h", "--help"], "show_default": True}
 )
 @click.rich_config(
@@ -116,266 +27,150 @@ config = copy.deepcopy(defaults)
         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),
+    type=click.Path(exists=True, dir_okay=False, readable=True, path_type=pathlib.Path),
+    default=Path.cwd() / "extracted",
     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'])}",
+    "-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(
-    "--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']}",
+    "-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.",
 )
-@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,
+def extract(
+    archive_path: pathlib.Path,
+    options: list[tuple[str, str]] | None,
+    extract_dir: pathlib.Path,
 ) -> 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 (
-                get_tracked_file_size() + extracted_size
-                > config["max_total_size_bytes"]
-            ):
-                click.echo(
-                    f"Skipped archive {file_path} because expected size {extracted_size} + current tracked files {get_tracked_file_size()} is greater than max_total_size_bytes {config['max_total_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:
+    """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."""
-    click.echo("------------------------------------------------")
+    logger.info("------------------------------------------------")
     for hash, info in tracked_files.items():
-        click.echo(f"Hash: {hash}")
-        click.echo(f"  Size: {info.get('size', 'Unknown')} bytes")
+        logger.info("Hash: %s", hash)
+        logger.info("  Size: %s bytes", info.get("size", "Unknown"))
         for path in info.get("paths", []):
-            click.echo(f"  Path: {path}")
-        click.echo("  Metadata:")
+            logger.info("  Path: %s", path)
+        logger.info("  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
-
+            logger.info("    %s: %s", key, value)
 
-def get_tracked_file_size() -> int:
-    """Get the total size of all tracked files.
 
-    Returns:
-        int: The total size in bytes.
-    """
-    return sum(tracked_files[hash].get("size", 0) for hash in tracked_files)
+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