crcutil 1.0.0__py3-none-any.whl

crcutil/__main__.py

@@ -0,0 +1,112 @@
+import json
+import sys
+
+from jsonschema.exceptions import ValidationError
+
+from crcutil.core.crc import Crc
+from crcutil.core.prompt import Prompt
+from crcutil.exception.bootstrap_error import BootstrapError
+from crcutil.exception.corrupt_hash_error import CorruptHashError
+from crcutil.exception.unexpected_argument_error import UnexpectedArgumentError
+from crcutil.exception.user_error import UserError
+from crcutil.util.crcutil_logger import CrcutilLogger
+from crcutil.util.file_importer import FileImporter
+
+
+def main() -> None:
+    try:
+        bootstrap_paths_dto = FileImporter.bootstrap()
+
+        log_dir = bootstrap_paths_dto.log_dir
+        hash_file_location = bootstrap_paths_dto.hash_file
+        report_file_location = bootstrap_paths_dto.report_file
+
+        log_config_file_path = (
+            FileImporter.get_project_root()
+            / "crcutil"
+            / "config"
+            / "log_config.yaml"
+        )
+
+        log_config = FileImporter.get_logging_config(log_config_file_path)
+
+        CrcutilLogger(log_dir, log_config)
+
+        instructions_dto = Prompt.get_user_instructions_dto()
+        location = instructions_dto.location
+        user_request = instructions_dto.request
+        hash_diff_files = instructions_dto.hash_diff_files
+        hash_diff_dtos = []
+        if hash_diff_files:
+            hash_diff_dtos = [
+                FileImporter.get_hash(x) for x in hash_diff_files
+            ]
+
+        crc_obj = Crc(
+            location=location,
+            hash_file_location=hash_file_location,
+            user_request=user_request,
+            hash_diff_1=hash_diff_dtos[0] if hash_diff_dtos else [],
+            hash_diff_2=hash_diff_dtos[1] if hash_diff_dtos else [],
+        )
+        hash_diff_report = crc_obj.do()
+        if hash_diff_report:
+            FileImporter.save_hash_diff_report(
+                report_file_location, hash_diff_report
+            )
+
+        sys.exit(0)
+
+    except SystemExit as e:
+        if e.code == 0:
+            description = "Successful System Exit"
+            CrcutilLogger.get_logger().debug(description)
+        else:
+            description = "\n=====Unexpected Error=====\n" f"{e!s}"
+            CrcutilLogger.get_logger().exception(description)
+            raise
+
+    except UnexpectedArgumentError as e:
+        sys.tracebacklimit = 0
+        description = (
+            "\n=====User Argument Error=====\n"
+            "These arguments are unrecognized: \n"
+        )
+        for argument in e.args[0]:
+            description += "-> " + argument + "\n"
+        CrcutilLogger.get_logger().error(description)
+        sys.exit(1)
+
+    except UserError as e:
+        sys.tracebacklimit = 0
+        description = "\n=====User Error=====\n" f"{e!s}"
+        CrcutilLogger.get_logger().error(description)
+
+    except CorruptHashError as e:
+        sys.tracebacklimit = 0
+        description = "\n=====Corrupt Hash Error=====\n" f"{e!s}"
+        CrcutilLogger.get_logger().error(description)
+
+    except json.decoder.JSONDecodeError as e:
+        sys.tracebacklimit = 0
+        description = "\n=====Corrupt Hash Error=====\n" f"{e!s}"
+        CrcutilLogger.get_logger().error(description)
+
+    except ValidationError as e:
+        sys.tracebacklimit = 0
+        description = "\n=====Invalid Schema Error=====\n" f"{e!s}"
+        CrcutilLogger.get_logger().error(description)
+
+    # No regular logger can be expected to be initialized
+    except BootstrapError as e:
+        description = "\n=====Program Initialization Error=====\n" f"{e!s}"
+        e.args = (description,)
+        raise
+
+    except Exception as e:  # noqa: BLE001
+        description = "\n=====Unexpected Error=====\n" f"{e!s}"
+        CrcutilLogger.get_logger().exception(description)
+
+
+if __name__ == "__main__":
+    main()

crcutil/config/log_config.yaml

@@ -0,0 +1,63 @@
+---
+version: 1
+disable_existing_loggers: False
+formatters:
+    console_color:
+        (): colorlog.ColoredFormatter
+        format: '%(log_color)s%(message)s%(reset)s'
+        log_colors:
+            DEBUG: cyan
+            WARNING: yellow
+            ERROR: red
+            CRITICAL: red,bg_white
+        datefmt: '%Y-%m-%dT%H:%M:%SZ'
+            
+    simple_color:
+        (): colorlog.ColoredFormatter
+        format: '%(log_color)s%(asctime)s %(levelname)-8s%(reset)s  %(message)s'
+        log_colors:
+            DEBUG: cyan
+            WARNING: yellow
+            ERROR: red
+            CRITICAL: red,bg_white
+        datefmt: '%Y-%m-%dT%H:%M:%SZ'
+        
+    detailed_color:
+        (): colorlog.ColoredFormatter
+        format: '%(log_color)s%(asctime)s | %(process)d | %(levelname)s | %(filename)s | %(lineno)d | %(funcName)s | %(message)s%(reset)s'
+        log_colors:
+            DEBUG: cyan
+            WARNING: yellow
+            ERROR: red
+            CRITICAL: red,bg_white
+        datefmt: '%Y-%m-%dT%H:%M:%SZ'
+
+    simple:
+        format: '%(asctime)s %(levelname)-8s  %(message)s'
+        datefmt: '%Y-%m-%dT%H:%M:%SZ'
+            
+    detailed:
+        format: '%(asctime)s | %(process)d | %(levelname)s | %(filename)s | %(lineno)d | %(funcName)s | %(message)s'
+        datefmt: '%Y-%m-%dT%H:%M:%SZ'
+        
+handlers:
+    console_color:
+        class: logging.StreamHandler
+        level: INFO
+        formatter: console_color
+        stream: ext://sys.stdout
+    
+    regular_file_handler:
+        filename: 'fallback_regular.log'
+        class: logging.FileHandler
+        level: DEBUG
+        formatter: detailed
+        encoding: utf8
+
+loggers:
+    console:
+        level: INFO
+        handlers: [console_color]
+    regular:
+        level: DEBUG
+        handlers: [console_color, regular_file_handler]

crcutil/core/crc.py

@@ -0,0 +1,290 @@
+from __future__ import annotations
+
+import sys
+import zlib
+from pathlib import Path
+
+from alive_progress import alive_bar
+
+from crcutil.core.prompt import Prompt
+from crcutil.dto.hash_diff_report_dto import HashDiffReportDTO
+from crcutil.dto.hash_dto import HashDTO
+from crcutil.enums.user_request import UserRequest
+from crcutil.exception.corrupt_hash_error import CorruptHashError
+from crcutil.util.crcutil_logger import CrcutilLogger
+from crcutil.util.file_importer import FileImporter
+from crcutil.util.keyboard_monitor import KeyboardMonitor
+
+
+class Crc:
+    def __init__(
+        self,
+        location: Path,
+        hash_file_location: Path,
+        user_request: UserRequest,
+        hash_diff_1: list[HashDTO],
+        hash_diff_2: list[HashDTO],
+    ) -> None:
+        self.location = location
+        self.hash_file_location = hash_file_location
+        self.user_request = user_request
+        self.hash_diff_1 = hash_diff_1
+        self.hash_diff_2 = hash_diff_2
+
+    def do(self) -> HashDiffReportDTO | None:
+        """
+        Performs a Hash/Diff
+
+        Returns:
+            HashDiffReportDTO | None: If request is Diff, None if Hash
+        Raises:
+            ValueError: If request other than diff or hash
+        """
+        if self.user_request is UserRequest.HASH:
+            match self.__get_hash_status():
+                case -1:
+                    self.__create_hash()
+                case 0:
+                    self.__continue_hash()
+                case 1:
+                    self.__create_hash(is_hash_overwrite=True)
+            return None
+        elif self.user_request is UserRequest.DIFF:
+            hash_1 = self.hash_diff_1
+            hash_2 = self.hash_diff_2
+
+            hash_1_dict = {dto.file: dto.crc for dto in hash_1}
+            hash_2_dict = {dto.file: dto.crc for dto in hash_2}
+
+            changes = [
+                dto
+                for dto in hash_2
+                if dto.file in hash_1_dict and hash_1_dict[dto.file] != dto.crc
+            ]
+            missing_1 = [
+                dto_1 for dto_1 in hash_1 if dto_1.file not in hash_2_dict
+            ]
+            missing_2 = [
+                dto_2 for dto_2 in hash_2 if dto_2.file not in hash_1_dict
+            ]
+
+            return HashDiffReportDTO(
+                changes=changes, missing_1=missing_1, missing_2=missing_2
+            )
+        else:
+            description = f"Unsupported request: {self.user_request!s}"
+            raise ValueError(description)
+
+    def __create_hash(self, is_hash_overwrite: bool = False) -> None:
+        if is_hash_overwrite:
+            Prompt.overwrite_hash_confirm()
+
+        self.hash_file_location.write_text("{}")
+
+        description = f"Creating Hash: {self.location}"
+        CrcutilLogger.get_logger().debug(description)
+
+        all_locations = self.seek(self.location)
+        self.__write_locations(all_locations)
+        self.__write_hash(self.location, all_locations)
+
+    def __continue_hash(self) -> None:
+        Prompt.continue_hash_confirm()
+        offset_position = ""
+
+        original_hashes = FileImporter.get_hash(self.hash_file_location)
+
+        description = (
+            f"Resuming existing Hash: {self.hash_file_location} "
+            f"with location: {self.location}"
+        )
+        CrcutilLogger.get_logger().debug(description)
+
+        for hash_dto in original_hashes:
+            if not hash_dto.crc:
+                offset_position = hash_dto.file
+                break
+
+        all_locations = self.seek(self.location)
+        for hash_dto in original_hashes:
+            if hash_dto.file not in all_locations:
+                description = (
+                    "An element in the Hash does not exist "
+                    f"in the supplied location: {hash_dto.file}\n"
+                    f"Cannot continue"
+                )
+                raise CorruptHashError(description)
+
+        original_hashes_str = [x.file for x in original_hashes]
+        for location in all_locations:
+            if location not in original_hashes_str:
+                description = (
+                    "An element in the supplied location does not exist "
+                    f"in the Hash: {location}\n"
+                    f"Cannot continue"
+                )
+                raise CorruptHashError(description)
+
+        filtered_locations = self.seek(self.location, offset_position)
+        self.__write_hash(
+            self.location, filtered_locations, len(original_hashes)
+        )
+
+    def __write_locations(self, str_relative_locations: list[str]) -> None:
+        hashes = [HashDTO(file=x, crc=0) for x in str_relative_locations]
+        FileImporter.save_hash(self.hash_file_location, hashes)
+
+    def __write_hash(
+        self,
+        parent_location: Path,
+        str_relative_locations: list[str],
+        total_count: int = 0,
+    ) -> None:
+        monitor = KeyboardMonitor()
+        try:
+            monitor.start()
+            play_icon, pause_icon = (
+                ("▶", "⏸")
+                if sys.stdout.encoding.lower().startswith("utf")
+                else (">", "||")
+            )
+
+            pause_description = "\n*Press p to pause/resume"
+            quit_description = "*Press q to quit"
+            CrcutilLogger.get_console_logger().info(pause_description)
+            CrcutilLogger.get_console_logger().info(quit_description)
+
+            length = (
+                total_count if total_count else len(str_relative_locations)
+            )
+            with alive_bar(length, dual_line=True) as bar:
+                if total_count:
+                    offset_count = total_count - len(str_relative_locations)
+                    for _ in range(offset_count):
+                        bar()
+
+                for str_relative_location in str_relative_locations:
+                    while monitor.is_paused:
+                        bar.text = f"{pause_icon} PAUSED"
+                    while monitor.is_quit:
+                        sys.exit(0)
+
+                    bar.text = f"{play_icon} {str_relative_location}"
+
+                    relative_location = Path(str_relative_location)
+                    abs_location = (
+                        parent_location / relative_location
+                    ).resolve()
+
+                    crc = self.__get_crc_hash(abs_location, parent_location)
+                    hashes = FileImporter.get_hash(self.hash_file_location)
+                    hashes.append(HashDTO(file=str_relative_location, crc=crc))
+
+                    FileImporter.save_hash(self.hash_file_location, hashes)
+
+                    bar()
+        except KeyboardInterrupt:
+            monitor.stop()
+
+    def __walk(self, path: Path) -> list[Path]:
+        """
+        Recursively collects all file/dirs in a given path
+
+        Args:
+            path (pathlib.Path): The parent directory to traverse
+
+        Returns:
+            [Path] All file/dir in the tree
+        """
+        items = []
+
+        if path.is_file():
+            items.append(path)
+        elif path.is_dir():
+            items.append(path)
+            for child in path.iterdir():
+                sub_items = self.__walk(child)
+                items.extend(sub_items)
+
+        return items
+
+    def seek(
+        self, initial_position: Path, offset_position: str = ""
+    ) -> list[str]:
+        raw = self.__walk(initial_position)
+        normalized = [x.relative_to(initial_position) for x in raw]
+        sorted_normalized = sorted(normalized, key=lambda path: path.name)
+        sorted_normalized = [str(x) for x in sorted_normalized if x != Path()]
+
+        if not offset_position:
+            return sorted_normalized
+        else:
+            is_collect = False
+            remaining = []
+            for item in sorted_normalized:
+                # Only flip once
+                if item == offset_position and not is_collect:
+                    is_collect = not is_collect
+                if is_collect:
+                    remaining.append(item)
+            return remaining
+
+    def __get_hash_status(self) -> int:
+        """
+        Gets the current status of a Hash file:
+        Possible values:
+        -1) File does not exist
+         0) File exists and is incomplete/pending
+         1) File exists and is finished
+
+        Returns:
+            int: The status of the hash file
+        """
+        status = -1
+        if self.hash_file_location.exists():
+            hash_dto = FileImporter.get_hash(self.hash_file_location)
+
+            for dto in hash_dto:
+                if not dto.crc:
+                    return 0
+
+            status = 1
+
+        return status
+
+    def __get_crc_hash(self, location: Path, parent_location: Path) -> int:
+        crc = 0
+        crc = (
+            zlib.crc32(
+                self.__get_crc_from_path(location, parent_location), crc
+            )
+            & 0xFFFFFFFF
+        )
+        crc = zlib.crc32(self.__get_crc_from_attr(location), crc) & 0xFFFFFFFF
+
+        if location.is_file():
+            crc = (
+                zlib.crc32(self.__get_crc_from_file_contents(location), crc)
+                & 0xFFFFFFFF
+            )
+
+        return crc
+
+    def __get_crc_from_path(
+        self, location: Path, parent_location: Path
+    ) -> bytes:
+        return str(location.relative_to(parent_location)).encode("utf-8")
+
+    def __get_crc_from_attr(self, location: Path) -> bytes:
+        stat = location.stat()
+        if location.is_dir():
+            return f"{stat.st_mode}".encode()
+        else:
+            return f"{stat.st_size}:{stat.st_mode}".encode()
+
+    def __get_crc_from_file_contents(self, location: Path) -> bytes:
+        file_crc = 0
+        with location.open("rb") as f:
+            for chunk in iter(lambda: f.read(4096), b""):
+                file_crc = zlib.crc32(chunk, file_crc) & 0xFFFFFFFF
+        return file_crc.to_bytes(4, "little", signed=False)

crcutil/core/prompt.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+import argparse
+import pathlib
+import sys
+from argparse import RawTextHelpFormatter
+from importlib.metadata import PackageNotFoundError, version
+
+from crcutil.dto.user_instructions_dto import UserInstructionsDTO
+from crcutil.enums.user_request import UserRequest
+from crcutil.exception.unexpected_argument_error import (
+    UnexpectedArgumentError,
+)
+from crcutil.exception.user_error import UserError
+from crcutil.util.crcutil_logger import CrcutilLogger
+from crcutil.util.file_importer import FileImporter
+from crcutil.util.static import Static
+
+EXPECTED_LOCATION_LENGHT_HASH = 1
+EXPECTED_LOCATION_LENGHT_DIFF = 2
+
+
+class Prompt(Static):
+    @staticmethod
+    def get_user_instructions_dto() -> UserInstructionsDTO:
+        parser = argparse.ArgumentParser(
+            description="crcutil", formatter_class=RawTextHelpFormatter
+        )
+
+        request_help_str = "Supported Requests: \n"
+
+        for request in list(UserRequest):
+            request_help_str += "-> " + request.value + "\n"
+
+        parser.add_argument(
+            "request",
+            metavar="Request",
+            type=str,
+            nargs="?",
+            help=request_help_str,
+        )
+
+        parser.add_argument(
+            "-l",
+            "--location",
+            metavar="location",
+            type=pathlib.Path,
+            nargs="*",
+            help=(
+                "Path to hash, or if requesting diff, "
+                "then path of both hash files to diff"
+            ),
+            default=[],
+        )
+
+        parser.add_argument(
+            "-v",
+            "--version",
+            action="store_true",
+            help=("Displays version"),
+        )
+
+        args, unknown = parser.parse_known_args()
+
+        if unknown:
+            raise UnexpectedArgumentError(unknown)
+
+        is_version = args.version
+
+        if is_version:
+            crcutil_version = ""
+
+            try:
+                crcutil_version = version("crcutil")
+
+            except PackageNotFoundError:
+                pyproject = FileImporter.get_pyproject()
+                crcutil_version = pyproject["project"]["version"]
+
+            CrcutilLogger.get_logger().info(crcutil_version)
+            sys.exit(0)
+
+        request = args.request
+        if not request:
+            description = "Expected a request but none supplied, see -h"
+            raise UserError(description)
+        request = UserRequest.get_user_request_from_str(request)
+
+        location = args.location
+        location_1 = pathlib.Path()
+        location_2 = pathlib.Path()
+        hash_diff_files = []
+        if args.location:
+            if (
+                len(args.location) == EXPECTED_LOCATION_LENGHT_HASH
+                and request is UserRequest.HASH
+            ):
+                location_1 = FileImporter.get_path_from_str(args.location[0])
+            elif (
+                len(args.location) == EXPECTED_LOCATION_LENGHT_DIFF
+                and request is UserRequest.DIFF
+            ):
+                location_1 = FileImporter.get_path_from_str(args.location[0])
+                location_2 = FileImporter.get_path_from_str(args.location[1])
+                hash_diff_files = [location_1, location_2]
+            elif (
+                len(args.location) != EXPECTED_LOCATION_LENGHT_DIFF
+                and request is UserRequest.DIFF
+            ):
+                description = (
+                    f"Expected 2 Hash files but got: "
+                    f"{len(args.location)}\n"
+                    f"Example: crcutil diff -l path_to_hash_1 path_to_hash_2"
+                )
+                raise UserError(description)
+        elif not args.location and request is UserRequest.DIFF:
+            description = (
+                "Expected 2 Hash files but got: 0\n"
+                "Example: crcutil diff -l path_to_hash_1 path_to_hash_2"
+            )
+            raise UserError(description)
+        else:
+            description = (
+                "Expected a location but none supplied\n"
+                "Example: crcutil hash -l path_to_hash"
+            )
+            raise UserError(description)
+
+        debug = (
+            "Received a User Request:\n"
+            f"Request: {request.value if request else None}\n"
+            f"Location: {location!s}\n"
+        )
+        CrcutilLogger.get_logger().debug(debug)
+
+        return UserInstructionsDTO(
+            request=request,
+            location=location_1,
+            hash_diff_files=hash_diff_files,
+        )
+
+    @staticmethod
+    def overwrite_hash_confirm() -> None:
+        warning = (
+            "⚠️"
+            if sys.stdout.encoding.lower().startswith("utf")
+            else "[WARNING]"
+        )
+        confirmation = (
+            input(f"{warning} Hash file already exists, " "OVERWRITE? (y/n): ")
+            .strip()
+            .lower()
+        )
+        if confirmation != "y":
+            debug = "Overwrite of hash file cancelled by user"
+            CrcutilLogger.get_logger().debug(debug)
+            sys.exit(0)
+
+    @staticmethod
+    def continue_hash_confirm() -> None:
+        warning = (
+            "⚠️"
+            if sys.stdout.encoding.lower().startswith("utf")
+            else "[WARNING]"
+        )
+        confirmation = (
+            input(
+                f"{warning} Incomplete Hash file already exists, "
+                "RESUME? (y/n): "
+            )
+            .strip()
+            .lower()
+        )
+        if confirmation != "y":
+            debug = "Resume of hash file cancelled by user"
+            CrcutilLogger.get_logger().debug(debug)
+            sys.exit(0)

crcutil/dto/bootstrap_paths_dto.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+
+# Frozen=True creates an implicit hash method, eq is created by default
+@dataclass(frozen=True)
+class BootstrapPathsDTO:
+    log_dir: Path
+    hash_file: Path
+    report_file: Path

crcutil/dto/hash_diff_report_dto.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from crcutil.dto.hash_dto import HashDTO
+
+
+from dataclasses import dataclass
+
+
+# Frozen=True creates an implicit hash method, eq is created by default
+@dataclass(frozen=True)
+class HashDiffReportDTO:
+    changes: list[HashDTO]
+    missing_1: list[HashDTO]
+    missing_2: list[HashDTO]

crcutil/dto/hash_dto.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+# Frozen=True creates an implicit hash method, eq is created by default
+@dataclass(frozen=True)
+class HashDTO:
+    file: str
+    crc: int

crcutil/dto/user_instructions_dto.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from crcutil.enums.user_request import UserRequest
+
+
+# Frozen=True creates an implicit hash method, eq is created by default
+@dataclass(frozen=True)
+class UserInstructionsDTO:
+    request: UserRequest
+    location: Path
+    hash_diff_files: list[Path]

crcutil/enums/user_request.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from enum import Enum
+
+
+class UserRequest(Enum):
+    HASH = "hash"
+    DIFF = "diff"
+
+    @staticmethod
+    def get_user_request_from_str(
+        user_request_candidate: str,
+    ) -> UserRequest:
+        requests = list(UserRequest)
+        user_request_candidate = user_request_candidate.lower()
+
+        for request in requests:
+            if (
+                user_request_candidate == request.value
+                or user_request_candidate.replace("_", " ") == request.value
+            ):
+                return request
+
+        raise ValueError("Request not supported: " + user_request_candidate)

crcutil/exception/bootstrap_error.py

@@ -0,0 +1,2 @@
+class BootstrapError(Exception):
+    pass

crcutil/exception/corrupt_hash_error.py

@@ -0,0 +1,2 @@
+class CorruptHashError(Exception):
+    pass

crcutil/exception/unexpected_argument_error.py

@@ -0,0 +1,2 @@
+class UnexpectedArgumentError(Exception):
+    pass

crcutil/exception/user_error.py

@@ -0,0 +1,2 @@
+class UserError(Exception):
+    pass

crcutil/serializer/hash_diff_report_serializer.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from crcutil.dto.hash_diff_report_dto import HashDiffReportDTO
+
+from crcutil.util.static import Static
+
+
+class HashDiffReportSerializer(Static):
+    @staticmethod
+    def to_json(dto: HashDiffReportDTO) -> dict:
+        obj = {}
+        changes = dto.changes
+        missing_1 = dto.missing_1
+        missing_2 = dto.missing_2
+
+        obj["Changes"] = [x.file for x in changes]
+        obj["Present in 1 Missing in 2"] = [x.file for x in missing_1]
+        obj["Present in 2 Missing in 1"] = [x.file for x in missing_2]
+        return obj
+
+    @staticmethod
+    def to_dto(hash_diff_report_dict: dict) -> HashDiffReportDTO:
+        raise NotImplementedError

crcutil/serializer/hash_serializer.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from crcutil.dto.hash_dto import HashDTO
+from crcutil.util.static import Static
+
+
+class HashSerializer(Static):
+    @staticmethod
+    def to_json(hash_dto: list[HashDTO]) -> dict:
+        return {dto.file: dto.crc for dto in hash_dto}
+
+    @staticmethod
+    def to_dto(hash_dict: dict) -> list[HashDTO]:
+        return [HashDTO(file=file, crc=crc) for file, crc in hash_dict.items()]

crcutil/util/crcutil_logger.py

@@ -0,0 +1,47 @@
+import logging
+
+# ruff: noqa: ANN002, ANN003, ANN204, RUF012
+import logging.config
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+class SingletonMeta(type):
+    _instances = {}
+
+    def __call__(cls, *args, **kwargs):
+        if cls not in cls._instances:
+            cls._instances[cls] = super().__call__(*args, **kwargs)
+        return cls._instances[cls]
+
+
+class CrcutilLogger(metaclass=SingletonMeta):
+    def __init__(self, log_dir: Path, log_config: dict) -> None:
+        if not hasattr(self, "initialized"):  # Avoid reinitialization
+            # Time data in UTC required by date named log files
+            day = str(datetime.now(timezone.utc).day)
+            month = str(datetime.now(timezone.utc).month)
+            year = str(datetime.now(timezone.utc).year)
+
+            log_file_name = f"{year}-{month}-{day}.log"
+            # Rewrite contents of YAML config to accomodate
+            # for date based log file names
+            log_config["handlers"]["regular_file_handler"]["filename"] = (
+                log_dir / log_file_name
+            )
+            # Load config with changes as Dict
+            logging.config.dictConfig(log_config)
+            # Initialize loggers
+            self.logger = logging.getLogger("regular")
+            self.console_logger = logging.getLogger("console")
+            self.initialized = True
+
+    @classmethod
+    def get_logger(cls) -> logging.Logger:
+        instance = cls._instances[cls]
+        return instance.logger
+
+    @classmethod
+    def get_console_logger(cls) -> logging.Logger:
+        instance = cls._instances[cls]
+        return instance.console_logger

crcutil/util/file_importer.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from crcutil.dto.hash_diff_report_dto import HashDiffReportDTO
+    from crcutil.dto.hash_dto import HashDTO
+
+
+import ctypes.wintypes
+import json
+import os
+import platform
+from pathlib import Path
+
+import toml
+
+from crcutil.dto.bootstrap_paths_dto import BootstrapPathsDTO
+from crcutil.exception.bootstrap_error import BootstrapError
+from crcutil.serializer.hash_diff_report_serializer import (
+    HashDiffReportSerializer,
+)
+from crcutil.serializer.hash_serializer import HashSerializer
+
+if platform.system() == "Windows":
+    import win32evtlog  # pyright: ignore # noqa: PGH003
+    import win32evtlogutil  # pyright: ignore # noqa: PGH003
+
+import yaml
+
+from crcutil.util.static import Static
+
+
+class FileImporter(Static):
+    encoding = "utf-8"
+
+    @staticmethod
+    def get_path_from_str(
+        path_candidate: str,
+        is_dir_expected: bool = False,
+        is_file_expected: bool = False,
+    ) -> Path:
+        """
+        Get pathlib.Path from a str
+
+        Args:
+            path_candidate (str): The likely Path
+            is_dir_expected (bool): Is the path expected to be a dir?
+            is_file_expected (bool): Is the path expected to be a file?
+
+        Returns:
+            A pathlib.Path
+
+        Raises:
+            ValueError: If path_candidate is not supplied or path doesn't exist
+            or path does not meet is_dir_expected/is_file_expected condition
+        """
+        if not path_candidate:
+            description = "Expected a path candidate but none supplied "
+            raise ValueError(description)
+
+        path = Path(path_candidate)
+
+        if not path.exists():
+            description = f"Path candidate ({path_candidate}) does not exist"
+            raise ValueError(description)
+
+        if is_dir_expected and not path.is_dir():
+            description = (
+                f"Expected a dir for ({path_candidate}) but this is not a dir"
+            )
+            raise ValueError(description)
+
+        if is_file_expected and not path.is_file():
+            description = (
+                f"Expected a file for ({path_candidate}) but path not a file"
+                f"candidate is not a file {path_candidate}"
+            )
+            raise ValueError(description)
+
+        return path
+
+    @staticmethod
+    def get_logging_config(logging_config_path: Path) -> dict:
+        with logging_config_path.open(
+            "r", errors="strict", encoding=FileImporter.encoding
+        ) as file:
+            return yaml.safe_load(file)
+
+    @staticmethod
+    def get_project_root() -> Path:
+        """
+        Gets the root of this project
+
+        Returns:
+            pathlib.Path: The project's root
+        """
+        return Path(__file__).parent.parent.parent
+
+    @staticmethod
+    def get_pyproject() -> dict:
+        return toml.load(
+            FileImporter.get_project_root().parent / "pyproject.toml"
+        )
+
+    @staticmethod
+    def save_hash(crc_path: Path, hash_dto: list[HashDTO]) -> None:
+        with crc_path.open(
+            "w", errors="strict", encoding=FileImporter.encoding
+        ) as file:
+            hash_data = HashSerializer.to_json(hash_dto)
+            json.dump(hash_data, file, indent=4)
+
+    @staticmethod
+    def save_hash_diff_report(
+        report_path: Path, hash_diff_report_dto: HashDiffReportDTO
+    ) -> None:
+        with report_path.open(
+            "w", errors="strict", encoding=FileImporter.encoding
+        ) as file:
+            hash_data = HashDiffReportSerializer.to_json(hash_diff_report_dto)
+            json.dump(hash_data, file, indent=4)
+
+    @staticmethod
+    def get_hash(crc_path: Path) -> list[HashDTO]:
+        with crc_path.open(
+            "r", errors="strict", encoding=FileImporter.encoding
+        ) as file:
+            return HashSerializer.to_dto(json.load(file))
+
+    @staticmethod
+    def bootstrap() -> BootstrapPathsDTO:
+        try:
+            home_folder = Path()
+            system = platform.system()
+
+            if system == "Windows":
+                csidl_personal = 5
+                shgfp_type_current = 0
+
+                buf = ctypes.create_unicode_buffer(ctypes.wintypes.MAX_PATH)
+                ctypes.windll.shell32.SHGetFolderPathW(  # pyright: ignore # noqa: PGH003
+                    None, csidl_personal, None, shgfp_type_current, buf
+                )
+                home_folder = buf.value or ""
+                if not home_folder:
+                    description = "Could not locate Documents folder"
+                    raise FileNotFoundError(description)  # noqa: TRY301
+            elif system == "Linux":
+                home_folder = os.getenv("HOME") or ""
+            else:
+                description = f"Unsupported OS: {system}"
+                raise OSError(description)  # noqa: TRY301
+
+            crcutil_dir = Path(home_folder) / "crcutil"
+            log_dir = crcutil_dir / "log"
+            hash_file = crcutil_dir / "hash.json"
+            report_file = crcutil_dir / "diff.json"
+
+            crcutil_dir.mkdir(exist_ok=True)
+            log_dir.mkdir(exist_ok=True)
+
+            return BootstrapPathsDTO(
+                log_dir=log_dir, hash_file=hash_file, report_file=report_file
+            )
+
+        except Exception as e:
+            if platform.system == "Windows":
+                win32evtlogutil.ReportEvent(  # pyright: ignore # noqa: PGH003
+                    "plexutil",
+                    eventID=1,
+                    eventType=win32evtlog.EVENTLOG_ERROR_TYPE,  # pyright: ignore # noqa: PGH003
+                    strings=[""],
+                )
+            if e.args and len(e.args) >= 0:
+                raise BootstrapError(e.args[0]) from e
+
+            raise BootstrapError from e

crcutil/util/keyboard_monitor.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from pynput import keyboard
+
+
+class KeyboardMonitor:
+    def __init__(self) -> None:
+        self.is_paused = False
+        self.is_quit = False
+        self.listener = None
+
+    def start(self) -> None:
+        self.listener = keyboard.Listener(on_press=self.on_press)
+        self.listener.start()
+
+    def stop(self) -> None:
+        if self.listener:
+            self.listener.stop()
+        self.is_quit = True
+
+    def on_press(self, key: keyboard.Key | keyboard.KeyCode | None) -> None:
+        try:
+            if key == keyboard.KeyCode.from_char("p"):
+                self.is_paused = not self.is_paused
+            if key == keyboard.KeyCode.from_char("q"):
+                self.stop()
+        except AttributeError:
+            pass

crcutil/util/static.py

@@ -0,0 +1,7 @@
+from typing import Self
+
+
+class Static:
+    def __new__(cls) -> Self:
+        description = "Static classes cannot be instantiated"
+        raise TypeError(description)

crcutil-1.0.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CARLOS FLOREZ
+
+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.

crcutil-1.0.0.dist-info/METADATA

@@ -0,0 +1,120 @@
+Metadata-Version: 2.2
+Name: crcutil
+Version: 1.0.0
+Author-email: Carlos Florez <carlos@florez.co.uk>
+Maintainer-email: Carlos Florez <carlos@florez.co.uk>
+License: MIT License
+        
+        Copyright (c) 2025 CARLOS FLOREZ
+        
+        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.
+        
+Project-URL: Repository, https://github.com/florez-carlos/crcutil
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.11.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: alive-progress==3.1.5
+Requires-Dist: pyyaml==6.0.1
+Requires-Dist: toml==0.10.2
+Requires-Dist: pywin32==306; sys_platform == "win32"
+Requires-Dist: jsonschema==4.23.0
+Requires-Dist: colorlog==6.4.0
+Requires-Dist: pynput==1.7.7
+
+# CRCUtil
+Recursively traverses a given location and generates a hash.json containing a CRC value for every encountered file/dir
+
+> [!NOTE]
+> Installation is supported only for the following: 
+> - Windows
+> - Linux
+
+> [!NOTE]
+> Development requires a fully configured [Dotfiles](https://github.com/florez-carlos/dotfiles) dev environment <br>
+
+## Table of Contents
+
+* [Installation](#installation)
+  * [pip](#pip)
+* [Usage](#usage)
+  * [hash](#hash)
+  * [diff](#diff)
+  * [pause/resume](#pauseresume)
+* [Development](#development)
+
+## Installation
+### Pip
+```bash
+python3 -m pip install crcutil
+```
+
+## Usage
+
+### Hash
+
+-l The location for which to generate the hash
+
+```bash
+crcutil hash -l C:\DESIRED\PATH
+```
+This will generate a hash.json file in: <br >
+- Windows
+```bash
+C:\Users\<USERNAME>\Documents\crcutil\
+```
+- Linux
+```bash
+$HOME/crcutil
+```
+### Diff
+If you hold 2 hashes generated from the same directory and would like to compare the differences.
+
+-l The location of both hash files to compare
+
+```bash
+crcutil diff -l C:\HASH_FILE_1.json C:\HASH_FILE_2.json
+```
+
+This will compare both hash files and generate a diff.json in:
+- Windows
+```bash
+C:\Users\<USERNAME>\Documents\crcutil\
+```
+- Linux
+```bash
+$HOME/crcutil
+```
+### Pause/Resume 
+- The program can be paused/resumed at any time by pressing p, if a CRC is being calculated for a file
+you have to wait for the calculation to complete before the program can pause.
+- If you exit the program or it crashes unexpectedly mid operation, invoke the same command and the program will continue where it left off,
+as long as the hash file is not corrupted
+
+## Development
+
+> [!NOTE]
+> Development requires a fully configured [Dotfiles](https://github.com/florez-carlos/dotfiles) dev environment <br>
+
+```bash
+source init.sh
+```
+
+

crcutil-1.0.0.dist-info/RECORD

@@ -0,0 +1,32 @@
+crcutil/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+crcutil/__main__.py,sha256=CfFljouHtIG0HSn7jPl5B3xMg-z40iI4NaxVDWb7LQo,3786
+crcutil/config/log_config.yaml,sha256=4hF_bhxLU2zSVY4hH-3jlNokbQ74n7jMimi8SMJqoAg,1827
+crcutil/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+crcutil/core/crc.py,sha256=qHawylqr3Ax0gElkLtqWof_19vSZOI9WdrE3h6F1HPI,9868
+crcutil/core/prompt.py,sha256=SM8iCheD_WU_3tFDedf1_mUCwRLedCk_DwTxLF7GnVE,5621
+crcutil/dto/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+crcutil/dto/bootstrap_paths_dto.py,sha256=yddkNWf9bjK2nQX5b8RgMOy5V7AN56ff99HNHuK-VpQ,242
+crcutil/dto/hash_diff_report_dto.py,sha256=JhkHt5aQMVthSIQ4_uRraR7SEgytLbEn8W6HuNhufmM,377
+crcutil/dto/hash_dto.py,sha256=QengNw1dd4o0zRHnf8ZsAS1jnQmlQmFW8tOpbhiMvNc,210
+crcutil/dto/user_instructions_dto.py,sha256=4dp-XBitsjgeqZn69cAnQfeGoADB9qanG8n84guRrm0,408
+crcutil/enums/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+crcutil/enums/user_request.py,sha256=yOR5hk7XJGHBFboDxrD4sj_WPnu9Vl1jZ6ruNInNUS8,643
+crcutil/exception/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+crcutil/exception/bootstrap_error.py,sha256=qB0xmmoJ-b44CPAvAyvUTWmnbmu6WL_Wawvs-5ZHdcY,42
+crcutil/exception/corrupt_hash_error.py,sha256=JaGdMvILUjx5cKd_Xc-9n_kfrGlZ_nuMWl10aOB-yS8,44
+crcutil/exception/unexpected_argument_error.py,sha256=YCqbzCmRwwESV0GjI_r9G3sUUWUI7bZygS21xyrFQ6Y,51
+crcutil/exception/user_error.py,sha256=g1b20vkPUokp1cOBW0IQlZx7y-yqOQJHSkI-nGXzcOY,37
+crcutil/serializer/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+crcutil/serializer/hash_diff_report_serializer.py,sha256=_Y7Uo7ps3OWw0zQOi6Ar34Kq-OyNvs9j56VbpR6VAoY,751
+crcutil/serializer/hash_serializer.py,sha256=UoooePyREyfS_M3ltJmD1SVjOk2lRMiODf69MCSGyrE,420
+crcutil/util/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+crcutil/util/crcutil_logger.py,sha256=2AKhPaHK5VTBHgrHQmYVr_ImnihjLuknUHb6dAjwnG8,1647
+crcutil/util/file_importer.py,sha256=P2EyiUAjbeYhDnKVRyyLgO4PDLdX2IPzRMG-6qaomWs,5785
+crcutil/util/keyboard_monitor.py,sha256=BbUXqXb2SHo8T1wJdUTuKnCW8mmqE8wmoVCjoDpB8ac,781
+crcutil/util/static.py,sha256=vx9yPhRtfeEwFszrs7VHz38R_AukdXBr-J2VBVnRklw,169
+crcutil-1.0.0.dist-info/LICENSE,sha256=VXEYCQROiczzjIGffiGDQGAUIKVWJwQQ84OQogJ3NsA,1070
+crcutil-1.0.0.dist-info/METADATA,sha256=9U5p_q_VS278vp0EYCzJ4WHwhASMGNHMubkHvUzgxg0,3698
+crcutil-1.0.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+crcutil-1.0.0.dist-info/entry_points.txt,sha256=CBOiMMOtkRvDjBre1UVuQY8Xfbt0QFILCI28NdW8fJc,50
+crcutil-1.0.0.dist-info/top_level.txt,sha256=HXu4JGsGLsOKjs9kzsJ4rzyFSF_UEoiBXuy_qtq4zz0,8
+crcutil-1.0.0.dist-info/RECORD,,

crcutil-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.8.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

crcutil-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+crcutil = crcutil.__main__:main

crcutil-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+crcutil