archae 2026.2.0__py3-none-any.whl

archae/util/file_tracker.py

@@ -0,0 +1,93 @@
+"""File tracking utilities for archae."""
+
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+
+class FileTracker:
+    """Manages file tracking by hash with metadata and paths."""
+
+    def __init__(self) -> None:
+        """Initialize the FileTracker."""
+        self.tracked_files: dict[str, dict] = {}
+
+    def track_file(self, file_hash: str, file_size_bytes: int) -> None:
+        """Track a file by its hash.
+
+        Args:
+            file_hash (str): The hash of the file to track.
+            file_size_bytes (int): The size of the file in bytes.
+        """
+        if file_hash not in self.tracked_files:
+            self.tracked_files[file_hash] = {}
+            self.tracked_files[file_hash]["size"] = file_size_bytes
+            self.tracked_files[file_hash]["metadata"] = {}
+        elif self.tracked_files[file_hash]["size"] != file_size_bytes:
+            msg = f"Hash collision detected for hash {file_hash} with differing sizes."
+            raise RuntimeError(msg)
+
+    def is_file_tracked(self, file_hash: str) -> bool:
+        """Check if a file is tracked by its hash.
+
+        Args:
+            file_hash (str): The hash of the file to check.
+
+        Returns:
+            bool: True if the file is tracked, False otherwise.
+        """
+        return file_hash in self.tracked_files
+
+    def get_tracked_file_metadata(self, file_hash: str) -> dict:
+        """Get metadata for a tracked file by its hash.
+
+        Args:
+            file_hash (str): The hash of the file.
+
+        Returns:
+            dict: The metadata of the tracked file.
+        """
+        return copy.deepcopy(self.tracked_files.get(file_hash, {}).get("metadata", {}))
+
+    def track_file_path(self, file_hash: str, file_path: Any) -> None:
+        """Track a file path by its hash.
+
+        Args:
+            file_hash (str): The hash of the file.
+            file_path: The path to track.
+        """
+        if "paths" not in self.tracked_files[file_hash]:
+            self.tracked_files[file_hash]["paths"] = []
+
+        if file_path not in self.tracked_files[file_hash]["paths"]:
+            self.tracked_files[file_hash]["paths"].append(file_path)
+
+    def add_metadata_to_hash(self, file_hash: str, key: str, value: Any) -> None:
+        """Add metadata to a tracked file.
+
+        Args:
+            file_hash (str): The hash of the file.
+            key (str): The metadata key.
+            value (Any): The metadata value.
+        """
+        self.tracked_files[file_hash]["metadata"][key] = value
+
+    def get_tracked_file_size(self) -> int:
+        """Get the total size of all tracked files.
+
+        Returns:
+            int: The total size in bytes.
+        """
+        return sum(
+            self.tracked_files[file_hash].get("size", 0)
+            for file_hash in self.tracked_files
+        )
+
+    def get_tracked_files(self) -> dict[str, dict]:
+        """Get all tracked files. This is a deep copy to prevent external modification.
+
+        Returns:
+            dict[str, dict]: The tracked files dictionary.
+        """
+        return copy.deepcopy(self.tracked_files)

archae/util/tool_manager.py

@@ -0,0 +1,112 @@
+"""Tool manager for locating and managing external archiving tools."""
+
+from __future__ import annotations
+
+import logging
+import shutil
+from typing import TYPE_CHECKING, ClassVar, cast
+
+import archae.util.archiver
+
+if TYPE_CHECKING:
+    from archae.util.archiver.base_archiver import BaseArchiver
+
+logger = logging.getLogger("archae")
+
+
+class ToolManager:
+    """Manager for locating and managing external archiving tools."""
+
+    __tools: ClassVar[dict[str, BaseArchiver]] = {}
+
+    @classmethod
+    def locate_tools(cls) -> None:
+        """Locate external tools."""
+        for archiver_cls in archae.util.archiver.BaseArchiver.__subclasses__():
+            logger.debug("Locating tool for %s", archiver_cls.archiver_name)
+            tool_path = shutil.which(str(archiver_cls.executable_name))
+            if tool_path:
+                logger.debug("Found %s at %s", archiver_cls.archiver_name, tool_path)
+                cls.__tools[str(archiver_cls.archiver_name)] = archiver_cls(tool_path)  # type: ignore[abstract]
+            else:
+                logger.warning(
+                    "MISSING_ARCHIVER: Could not find %s; some archive types may not be supported",
+                    archiver_cls.archiver_name,
+                )
+
+    @classmethod
+    def get_supported_extensions(cls) -> list[str]:
+        """Get a sorted list of all file extensions supported by located tools.
+
+        Returns:
+            list[str]: Sorted list of supported file extensions.
+        """
+        supported: set[str] = set()
+        for tool in cls.__tools.values():
+            supported.update(tool.file_extensions)
+        return sorted(supported)
+
+    @classmethod
+    def get_unsupported_extensions(cls) -> list[str]:
+        """Get a sorted list of all file extensions from all archiver subclasses that are not currently supported.
+
+        Returns:
+            list[str]: Sorted list of unsupported file extensions.
+        """
+        all_extensions: set[str] = set()
+        supported: set[str] = set()
+
+        # Get all extensions from all archiver classes
+        for archiver_cls in archae.util.archiver.BaseArchiver.__subclasses__():
+            all_extensions.update(cast("list[str]", archiver_cls.file_extensions))
+
+        # Get supported extensions from located tools
+        for tool in cls.__tools.values():
+            supported.update(tool.file_extensions)
+
+        # Return the difference
+        unsupported = all_extensions - supported
+        return sorted(unsupported)
+
+    @classmethod
+    def get_supported_mime_types(cls) -> list[str]:
+        """Get a sorted list of all MIME types supported by located tools.
+
+        Returns:
+            list[str]: Sorted list of supported MIME types.
+        """
+        supported: set[str] = set()
+        for tool in cls.__tools.values():
+            supported.update(tool.mime_types)
+        return sorted(supported)
+
+    @classmethod
+    def get_unsupported_mime_types(cls) -> list[str]:
+        """Get a sorted list of all MIME types from all archiver subclasses that are not currently supported.
+
+        Returns:
+            list[str]: Sorted list of unsupported MIME types.
+        """
+        all_mime_types: set[str] = set()
+        supported: set[str] = set()
+
+        # Get all MIME types from all archiver classes
+        for archiver_cls in archae.util.archiver.BaseArchiver.__subclasses__():
+            all_mime_types.update(cast("list[str]", archiver_cls.mime_types))
+
+        # Get supported MIME types from located tools
+        for tool in cls.__tools.values():
+            supported.update(tool.mime_types)
+
+        # Return the difference
+        unsupported = all_mime_types - supported
+        return sorted(unsupported)
+
+    @classmethod
+    def get_tools(cls) -> dict[str, BaseArchiver]:
+        """Get a shallow copy of the tools dictionary.
+
+        Returns:
+            dict[str, BaseArchiver]: A shallow copy of the tools dictionary.
+        """
+        return cls.__tools.copy()

archae-2026.2.0.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.3
+Name: archae
+Version: 2026.2.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.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-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
+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 -->
+
+## 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 -->
+
+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
+
+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:
+
+<!-- [[[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] COMMAND [ARGS]...
+
+ Archae explodes archives.
+
+╭─ Options ────────────────────────────────────────────────────────────────────────────╮
+│ --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.                              │
+╰──────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+<!-- [[[end]]] -->
+
+<!-- end docs-include-usage -->
+
+## TODOs
+
+- 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
+- Detect password-protected archives
+- Allow supplying archive passwords by hash
+- Add custom magic to detect obscure archive formats

archae-2026.2.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+archae/__init__.py,sha256=O_HNvpNVsJ5LZPNPLvuHhHdOq0b6M0LnWqycB505mkQ,111
+archae/__main__.py,sha256=l3eO5dEs1cR_hDziOpnW1PYzoRL2siYm81wgvftyigg,172
+archae/cli.py,sha256=ZYq7joe10y73dCwQY7666m-SY2dej_GVEmoYRyFpg7A,5739
+archae/config.py,sha256=zGOwkPDfNLR-06ziZMXeLBamd-98AbNU0aTuoH7ibKQ,2952
+archae/default_settings.toml,sha256=svBdN9QJm8UBBz6AEWpBp-gslSBcE5n00xZdl32KDEc,230
+archae/extractor.py,sha256=CfYtsxuoXQ2rOLQIByJvLI9Y61U338dZoeb7ZBWAc_g,9948
+archae/options.yaml,sha256=nJo7gOCuiS_fKd9C3iRwI3Eb_f4OT6mbdVkipqdISpk,937
+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=xEHynzmhwZdMl2fEDj9h-YaH9ZQEeaugF4H_ILoOxTY,1629
+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/converter/file_size.py,sha256=BdcYzpdvCDq3YH1eYW1-zwnQCxv9mBzG4DuqHY2dt6o,1984
+archae/util/enum/__init__.py,sha256=IvjtVopATKLAHDjOpblaExy2yXwIzweX0HoUrQWcpkM,109
+archae/util/enum/byte_scale.py,sha256=5TZG1msPmJU9whZtKAywZtKOre6p2xMJ2y0gE4TG3OE,1593
+archae/util/file_tracker.py,sha256=HQb1l7j_Jy0qO6tqkB8jXM6P2o5fLB6Ih0J5U4JUyT8,3106
+archae/util/tool_manager.py,sha256=HU2xkmb_18XF5SFwFV5gUUcPddZVBYRdGB2PSWgWaqA,3974
+archae-2026.2.0.dist-info/WHEEL,sha256=fAguSjoiATBe7TNBkJwOjyL1Tt4wwiaQGtNtjRPNMQA,80
+archae-2026.2.0.dist-info/entry_points.txt,sha256=gGL_R78QELaTeyFGb-OuSnRuu4EUdT68EKmyrFno59o,48
+archae-2026.2.0.dist-info/METADATA,sha256=C-zA6mJjkd8Ii6vBsVAsEvc8VA20acPGqa3A38950As,7974
+archae-2026.2.0.dist-info/RECORD,,

archae-2026.2.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.2.0.dist-info/entry_points.txt

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