archae 2026.1.0__tar.gz → 2026.2.0__tar.gz

{archae-2026.1.0 → archae-2026.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: archae
-Version: 2026.1.0
+Version: 2026.2.0
 Summary: Archae explodes archives.
 Keywords: 
 Author: Shawn McNaughton
@@ -32,16 +32,19 @@ 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: dynaconf>=3.2.12
+Requires-Dist: platformdirs>=4.5.1
 Requires-Dist: python-magic
+Requires-Dist: pyyaml>=6.0.3
 Requires-Dist: rich-click
-Requires-Python: ~=3.11
+Requires-Dist: types-pyyaml>=6
+Requires-Python: >=3.12
 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
@@ -65,6 +68,27 @@ Archae explodes archives.
 
 <!-- end docs-include-index -->
 
+## Why
+
+Every once and a while, I run into an issue: multiple layers of archives. The reasons vary, but examples would include:
+
+- Searching for something in a ZIP of folders that contained a ZIP with a CD image in it
+- Running a malware scan and finding an obscure archive format was missed and not even flagged
+  Meanwhile, I want to make sure I don't fill my disk, especially if an archive bomb (more commonly known as a ZIP bomb) has been jammed in somewhere. They're only funny the first time. :D
+
+## 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
+- Detects duplicate archives
+- Basic archive bomb protections
+    - MAX_ARCHIVE_SIZE_BYTES - ensures the uncompressed size of an archive is limited
+    - MAX_TOTAL_SIZE_BYTES - ensures the total extracted footprint isn't above a certain size
+    - MIN_ARCHIVE_RATIO - ensures very-high-compression-ratio archives are stopped
+    - MIN_DISK_FREE_SPACE - minimum free space at the extraction location
+    - MAX_DEPTH - allow setting a maximum archive depth to traverse
+
 ## Installation
 
 <!-- start docs-include-installation -->
@@ -83,6 +107,13 @@ Check out the [Archae documentation](https://archae.readthedocs.io/en/stable/) f
 
 ## Usage
 
+Configuration values are supplied one of four ways, and any item lower in this list will overwrite a prior one:
+
+- Default values are stored in the app
+- A TOML file at ~/.config/archae/ will be created on first run and can override those values (ex. MIN_ARCHIVE_RATIO = 0.005)
+- Env vars starts starting with "ARCHAE\_" are parsed (ex. ARCHAE_MIN_ARCHIVE_RATIO=0.005)
+- Values can be passed in as flags (ex. --min_archive_ratio=0.005)
+
 <!-- start docs-include-usage -->
 
 Running `archae --help` or `python -m archae --help` shows a list of all of the available options and arguments:
@@ -100,28 +131,18 @@ cog.outl(f"\n```sh\narchae --help\n{help.rstrip()}\n```\n")
 ```sh
 archae --help
 
- Usage: archae [OPTIONS] ARCHIVE_PATH
+ Usage: archae [OPTIONS] COMMAND [ARGS]...
 
  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.     │
+│ --version  -v  Show the version and exit.                                            │
+│ --help     -h  Show this message and exit.                                           │
+╰──────────────────────────────────────────────────────────────────────────────────────╯
+╭─ Commands ───────────────────────────────────────────────────────────────────────────╮
+│ extract         Extract and analyze an archive.                                      │
+│ listopts        List all available configuration options.                            │
+│ status          Show archae status and available tools.                              │
 ╰──────────────────────────────────────────────────────────────────────────────────────╯
 ```
 
@@ -129,19 +150,12 @@ archae --help
 
 <!-- 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)
+- More archive bomb protections
+    - delete_archives_as_exploded - remove archive files to reduce duplication (boolean)
 - 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 → archae-2026.2.0}/README.md

@@ -15,6 +15,27 @@ Archae explodes archives.
 
 <!-- end docs-include-index -->
 
+## Why
+
+Every once and a while, I run into an issue: multiple layers of archives. The reasons vary, but examples would include:
+
+- Searching for something in a ZIP of folders that contained a ZIP with a CD image in it
+- Running a malware scan and finding an obscure archive format was missed and not even flagged
+  Meanwhile, I want to make sure I don't fill my disk, especially if an archive bomb (more commonly known as a ZIP bomb) has been jammed in somewhere. They're only funny the first time. :D
+
+## 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
+- Detects duplicate archives
+- Basic archive bomb protections
+    - MAX_ARCHIVE_SIZE_BYTES - ensures the uncompressed size of an archive is limited
+    - MAX_TOTAL_SIZE_BYTES - ensures the total extracted footprint isn't above a certain size
+    - MIN_ARCHIVE_RATIO - ensures very-high-compression-ratio archives are stopped
+    - MIN_DISK_FREE_SPACE - minimum free space at the extraction location
+    - MAX_DEPTH - allow setting a maximum archive depth to traverse
+
 ## Installation
 
 <!-- start docs-include-installation -->
@@ -33,6 +54,13 @@ Check out the [Archae documentation](https://archae.readthedocs.io/en/stable/) f
 
 ## Usage
 
+Configuration values are supplied one of four ways, and any item lower in this list will overwrite a prior one:
+
+- Default values are stored in the app
+- A TOML file at ~/.config/archae/ will be created on first run and can override those values (ex. MIN_ARCHIVE_RATIO = 0.005)
+- Env vars starts starting with "ARCHAE\_" are parsed (ex. ARCHAE_MIN_ARCHIVE_RATIO=0.005)
+- Values can be passed in as flags (ex. --min_archive_ratio=0.005)
+
 <!-- start docs-include-usage -->
 
 Running `archae --help` or `python -m archae --help` shows a list of all of the available options and arguments:
@@ -50,28 +78,18 @@ cog.outl(f"\n```sh\narchae --help\n{help.rstrip()}\n```\n")
 ```sh
 archae --help
 
- Usage: archae [OPTIONS] ARCHIVE_PATH
+ Usage: archae [OPTIONS] COMMAND [ARGS]...
 
  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.     │
+│ --version  -v  Show the version and exit.                                            │
+│ --help     -h  Show this message and exit.                                           │
+╰──────────────────────────────────────────────────────────────────────────────────────╯
+╭─ Commands ───────────────────────────────────────────────────────────────────────────╮
+│ extract         Extract and analyze an archive.                                      │
+│ listopts        List all available configuration options.                            │
+│ status          Show archae status and available tools.                              │
 ╰──────────────────────────────────────────────────────────────────────────────────────╯
 ```
 
@@ -79,19 +97,12 @@ archae --help
 
 <!-- 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)
+- More archive bomb protections
+    - delete_archives_as_exploded - remove archive files to reduce duplication (boolean)
 - 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 → archae-2026.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "archae"
-version = "2026.1.0"
+version = "2026.2.0"
 description = "Archae explodes archives."
 authors = [{name = "Shawn McNaughton", email = "shawngmc@gmail.com"}]
 readme = "README.md"
@@ -17,18 +17,21 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
     "Programming Language :: Python :: 3 :: Only",
     "Typing :: Typed",
 ]
-requires-python = "~=3.11"
+requires-python = ">=3.12"
 dependencies = [
     "click",
+    "dynaconf>=3.2.12",
+    "platformdirs>=4.5.1",
     "python-magic",
+    "PyYAML>=6.0.3",
     "rich_click",
+    "types-PyYAML>=6",
 ]
 
 [dependency-groups]

archae-2026.2.0/src/archae/__init__.py

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

archae-2026.2.0/src/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-2026.2.0/src/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-2026.2.0/src/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