builder_peppermint_void/builder/core/utils.py

# -*- coding: utf-8 -*-
"""
SPDX-FileCopyrightText: 2023-2025 PeppermintOS Team
(peppermintosteam@proton.me)

SPDX-License-Identifier: GPL-3.0-or-later

This module provides a collection of utility functions used throughout the PeppermintOS Builder project.
It includes functions for logging messages at different levels, ensuring directory existence,
copying files and directories, and checking the existence of paths.

The aim of this module is to centralize common operations, promoting code reusability and
simplifying the development process of the ISO builder.

Credits:
  - PeppermintOS Team (peppermintosteam@proton.me) - Development and maintenance of the project.

License:
  This code is distributed under the GNU General Public License version 3 or later (GPL-3.0-or-later).
  For more details, please refer to the LICENSE file included in the project or visit:
  https://www.gnu.org/licenses/gpl-3.0.html
"""

import logging
import subprocess
import sys
import os
import shutil

BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
sys.path.insert(0, BASE_DIR)

try:
    from builder.core.bootstrap.paths import paths
    from builder.configs import logger_config  # Import the logger_config module
    logger = logger_config.setup_logger('utils')  # Pass the 'utils' argument
except ImportError as e:
    print(f"Error importing necessary modules: {e}. Ensure your environment is set up correctly.")
    sys.exit(1)


def info_message(message):
    """Logs an informational message."""
    logger.info(f"INFO: {message}")

def error_message(message):
    """Logs an error message."""
    logger.error(f"ERROR: {message}")

def debug_message(message):
    """Logs a debug message."""
    logger.debug(f"DEBUG: {message}")

def warning_message(message):
    """Logs a warning message."""
    logger.warning(f"WARNING: {message}")

def ensure_directory_exists(dir_path, create_parents=True):
    """
    Ensures that the directory exists, creating it if necessary.

    Args:
        dir_path (str): The path to the directory.
        create_parents (bool, optional): If True, creates parent directories as needed. Defaults to True.

    Raises:
        FileNotFoundError: If create_parents is False and the parent directory does not exist.
        OSError: If an error occurs while creating the directory (except for the case where the directory already exists due to concurrency).
    """
    if not os.path.exists(dir_path):
        logger.info(f"=> Creating directory: {dir_path}")
        try:
            os.makedirs(dir_path, exist_ok=True)
        except FileNotFoundError:
            if create_parents:
                parent_dir = os.path.dirname(dir_path)
                if parent_dir and not os.path.exists(parent_dir):
                    ensure_directory_exists(parent_dir, create_parents=True)
                os.makedirs(dir_path, exist_ok=True)
            else:
                raise
        except OSError as e:
            if e.errno == 17 and os.path.isdir(dir_path):
                logger.debug(f"=> Directory already exists (expected error due to concurrency): {dir_path}")
            else:
                raise
    else:
        logger.debug(f"=> Directory already exists: {dir_path}")


def copy_file(source_path, dest_path):
    """
    Copies a file from a source path to a destination path, preserving metadata (like timestamps).

    Args:
        source_path (str): The path to the source file.
        dest_path (str): The path to the destination file.

    Returns:
        bool: True if the file was copied successfully, False if an error occurred.
    """
    try:
        shutil.copy2(source_path, dest_path)
        logger.debug(f"=> File copied from: {source_path} to: {dest_path}")
        return True
    except FileNotFoundError:
        logger.error(f"Error copying file: Source file not found: {source_path}")
        return False
    except OSError as e:
        logger.error(f"Error copying file from: {source_path} to: {dest_path}")
        logger.error(f"Error details: {e}")
        return False


def copy_directory(source_dir, dest_dir, merge=False):
    """
    Copies a directory from a source directory to a destination directory.

    Args:
        source_dir (str): The path to the source directory.
        dest_dir (str): The path to the destination directory.
        merge (bool): If True, merges the source directory into the destination directory if it already exists (uses shutil.copytree with dirs_exist_ok=True).
                      If False, replaces the destination directory if it already exists (uses shutil.copytree without dirs_exist_ok=True). Defaults to False.

    Returns:
        bool: True if the directory was copied successfully, False if an error occurred.
    """
    try:
        if merge:
            shutil.copytree(source_dir, dest_dir, dirs_exist_ok=True)
            logger.debug(f"=> Directory merged from: {source_dir} to: {dest_dir}")
        else:
            shutil.copytree(source_dir, dest_dir)
            logger.debug(f"=> Directory copied from: {source_dir} to: {dest_dir}")
        return True
    except FileNotFoundError:
        logger.error(f"Error copying directory: Source directory not found: {source_dir}")
        return False
    except FileExistsError:
        logger.error(f"Error copying directory: Destination directory already exists and merge=False: {dest_dir}")
        return False
    except OSError as e:
        logger.error(f"Error copying directory from: {source_dir} to: {dest_dir}")
        logger.error(f"Error details: {e}")
        return False


def check_path_exists(path):
    """
    Checks if a path (file or directory) exists.

    Args:
        path (str): The path to check.

    Returns:
        bool: True if the path exists, False otherwise.
    """
    path_exists = os.path.exists(path)
    if path_exists:
        logger.debug(f"=> Path exists: {path}")
    else:
        logger.debug(f"=> Path does NOT exist: {path}")
    return path_exists