sc-foundation-services 3.0.2__py3-none-any.whl

sc_foundation/__init__.py

@@ -0,0 +1,14 @@
+"""
+sc-foundation package.
+
+This package provides functions and classes for the Spello Consulting Foundation package.
+"""
+from .sc_common import SCCommon
+from .sc_config_mgr import SCConfigManager
+from .sc_csv_reader import CSVReader
+from .sc_date_helper import DateHelper
+from .sc_json_encoder import JSONEncoder
+from .sc_logging import SCLogger
+from .validation_schema import yaml_config_validation
+
+__all__ = ["CSVReader", "DateHelper", "JSONEncoder", "SCCommon", "SCConfigManager", "SCLogger", "yaml_config_validation"]

sc_foundation/sc_common.py

@@ -0,0 +1,349 @@
+"""Common functions and classes used by other classes in the sc_foundation package."""
+
+import ipaddress
+import os
+import platform
+import re
+import subprocess  # noqa: S404
+from pathlib import Path
+
+import httpx
+import validators
+
+
+class SCCommon:
+    """Common functions and classes used by other classes in the sc_foundation package."""
+
+    @staticmethod
+    def is_valid_hostname(target: str) -> bool:
+        """Return whether target is a valid IPv4, IPv6, or DNS hostname.
+
+        Args:
+            target: The target string to validate.
+
+        Returns:
+            A boolean indicating validity.
+        """
+        result, _ = SCCommon.check_hostname_and_type(target)
+        return result
+
+    @staticmethod
+    def check_hostname_and_type(target: str) -> tuple[bool, str | None]:
+        """Return whether target is a valid IPv4, IPv6, or DNS hostname. Also returns the type.
+
+        Args:
+            target: The target string to validate.
+
+        Returns:
+            A tuple containing a boolean indicating validity and a string indicating the type ('ipv4', 'ipv6', or 'hostname').
+        """
+        # Make sure the target is a string
+        if not isinstance(target, str):
+            return False, None
+
+        # Check strict IPv4
+        try:
+            ipaddress.IPv4Address(target)
+        except ValueError:
+            pass
+        else:
+            if target.count(".") == 3:
+                return True, "ipv4"
+
+        # Check strict IPv6
+        try:
+            ipaddress.IPv6Address(target)
+        except ValueError:
+            pass
+        else:
+            # If it is a valid IPv6 address, return True
+            return True, "ipv6"
+
+        # Reject if it looks like a malformed IP (like 192.168.1 or 256.1.1.1)
+        if re.fullmatch(r"[0-9.]+", target):
+            return False, None
+
+        # Validate hostname using validators library
+        if validators.domain(target) or validators.hostname(target, rfc_1034=True):
+            return True, "hostname"
+
+        return False, None
+
+    @staticmethod
+    def ping_host(ip_address: str, timeout: int = 1) -> bool:
+        """Pings an IP address and returns True if the host is responding, False otherwise.
+
+        Args:
+            ip_address: The IP address to ping.
+            timeout: Timeout in seconds for the ping response. Default is 1 second.
+
+        Raises:
+            RuntimeError: If the IP address is invalid or the ping system call fails.
+
+        Returns:
+            result (bool): True if the host responds, False otherwise.
+        """
+        # Determine the ping command based on the operating system
+        param = "-n" if platform.system().lower() == "windows" else "-c"
+
+        if not SCCommon.is_valid_hostname(ip_address):
+            error_msg = f"Invalid IP address: {ip_address}"
+            raise RuntimeError(error_msg)
+
+        command = ["ping", param, "1", "-W", str(timeout), ip_address]
+
+        try:
+            # Run the ping command using subprocess for better security
+            result = subprocess.run(command, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, shell=False, check=False)  # noqa: S603
+            response_code = result.returncode
+        except OSError as e:
+            error_msg = f"Error pinging {ip_address}: {e}"
+            raise RuntimeError(error_msg) from e
+        else:
+            # Return True if the ping was successful (exit code 0)
+            return response_code == 0
+
+    @staticmethod
+    def check_internet_connection(urls=None, timeout: int = 3) -> bool:
+        """Check if the system has an active internet connection by trying to open a connection to common websites.
+
+        Args:
+            urls (list): A list of URLs to check for internet connectivity. Defaults to common DNS servers and websites.
+            timeout (int): The timeout in seconds for each request.
+
+        Returns:
+            True if the system is connected to the internet, False otherwise.
+        """
+        if urls is None:
+            urls = [
+                "https://1.1.1.1",         # Cloudflare DNS
+                "https://8.8.8.8",         # Google DNS
+                "https://www.google.com",
+                "https://www.cloudflare.com"
+            ]
+
+        for url in urls:
+            try:
+                response = httpx.get(url, timeout=timeout, follow_redirects=True)
+                if response.status_code < 400:
+                    return True
+            except httpx.RequestError:
+                continue
+        return False
+
+    @staticmethod
+    def get_os() -> str:
+        """Return the name of the operating system.
+
+        Returns:
+            The name of the operating system in lowercase.
+        """
+        # Get the platform name and convert it to lowercase
+        platform_name = platform.system().lower()
+
+        if platform_name == "darwin":
+            platform_name = "macos"
+
+        return platform_name
+
+    @staticmethod
+    def is_probable_path(possible_path: str | Path) -> bool:
+        """Check if the given string or Path object is likely to be a file path.
+
+        This method checks if the string is an absolute path, contains a path separator, or has a file extension.
+
+        Args:
+            possible_path: The string to check.
+
+        Returns:
+            True if the string is likely a file path, False otherwise.
+        """
+        max_path = 260 if SCCommon.get_os() == "windows" else os.pathconf("/", "PC_PATH_MAX")
+
+        path_obj = None
+        if isinstance(possible_path, Path):
+            path_str = str(possible_path)
+            path_obj = possible_path
+        else:
+            path_str = possible_path
+
+        if len(path_str) > max_path:
+            # If the path is longer than the maximum allowed path length, it cannot be a valid path
+            return False
+
+        if path_obj is None:
+            path_obj = Path(possible_path)
+
+        # Check if it's absolute, or contains a path separator, or has a file extension
+        if path_obj.is_absolute():
+            return True
+
+        if "/" in path_str or "\\" in path_str:
+            return True
+
+        # Check if the path has a file extension
+        return bool(path_obj.suffix and path_obj.suffix.lower() is not None)
+
+    @staticmethod
+    def get_project_root(marker_files=("pyproject.toml", ".project_root", "uv.lock", ".git")) -> Path:
+        """Return the root folder of the Python project.
+
+        By default, this function looks for marker files like pyproject.toml, .project_root, uv.lock, or .git to
+        identify the project root. It starts from the directory of this file and walks upwards until it finds one
+        of the marker files. If it cannot find any of the marker files, it raises a RuntimeError.
+
+        If the environment variable SC_FOUNDATION_PROJECT_ROOT is set, it will check if that path exists and is a directory,
+        and return it as the project root if so. This allows users to override the automatic detection of the project
+        root if needed (e.g., if they have an unusual project structure or want to use the foundation in a different project
+        without copying this file).
+
+        Args:
+            marker_files (tuple): A tuple of file names that indicate the project root.
+
+        Raises:
+            RuntimeError: If the project root cannot be found.
+
+        Returns:
+            root_dir (Path): The root folder of the Python project as a Path object.
+        """
+        path = None
+        env_path = os.environ.get("SC_FOUNDATION_PROJECT_ROOT")        # Issue 32
+        if env_path:
+            path = Path(env_path).resolve()
+        if path and path.exists() and path.is_dir():
+            return path
+
+        # Default behaviour is to look for the project root based on the location of this file and the presence of marker files. This allows the foundation to be used in other projects without requiring users
+        path = Path(__file__).resolve()
+
+        # Walk upwards until we find a marker file
+        for parent in [path, *list(path.parents)]:
+            for marker in marker_files:
+                if (parent / marker).exists():
+                    return parent
+
+        error_msg = f"Project root not found. Looked for markers: {marker_files}"
+        if env_path:
+            error_msg += f" (also checked SC_FOUNDATION_PROJECT_ROOT={env_path})"
+        raise RuntimeError(error_msg)
+
+    @staticmethod
+    def select_file_location(file_name: str, create_folder: bool = False) -> Path | None:
+        """Select the file location for the given file name. It resolves an absolute path for the file_name as follows.
+
+        1. If file_name is an absolute path, return it as a Path object.
+        2. If file_name is a relative path (contains parent directories), return the absolute path based on the current working directory.
+        3. If file_name is just a file name, look for it in the current working directory first, then in the root directory.
+
+        The root directly is defined as the directory containing the main script being executed (the module containing __main__).
+
+        Raises:
+            RuntimeError: If the project root cannot be determined.
+
+        Args:
+            file_name: The name of the file to locate. Can be just a file name, or a relative or absolute path.
+            create_folder: If True, create the parent folder if it does not exist. Default is False.
+
+        Returns:
+            file_path (Path): The full path to the file as a Path object. None if the file_name does not appear to be a path.
+        """
+        return_file_path = None
+
+        # Look at the file_name and see if it looks like a path
+        if not SCCommon.is_probable_path(file_name):
+            return None
+
+        # Check to see if file_name is a full path or just a file name
+        return_file_path = Path(file_name)
+
+        # Check if file_name is an absolute path, return this even if it does not exist
+        if return_file_path.is_absolute():
+            SCCommon._create_folder_if_not_exists(return_file_path.parent) if create_folder else None
+            return return_file_path
+
+        # Check if file_name contains any parent directories (i.e., is a relative path)
+        # If so, return this even if it does not exist
+        if return_file_path.parent != Path("."):  # noqa: PTH201
+            # It's a relative path
+            return_file_path = (Path.cwd() / return_file_path).resolve()
+            SCCommon._create_folder_if_not_exists(return_file_path.parent) if create_folder else None
+            return return_file_path
+
+        # Otherwise, assume it's just a file name and look for it in the current directory and the script directory
+        current_dir = Path.cwd()
+        return_file_path = current_dir / file_name
+        if not return_file_path.exists():
+            try:
+                project_root_dir = SCCommon.get_project_root()
+                return_file_path = project_root_dir / file_name
+            except RuntimeError as e:
+                error_msg = f"Cannot determine project root to locate file '{file_name}': {e}"
+                raise RuntimeError(error_msg) from e
+
+        if return_file_path:
+            SCCommon._create_folder_if_not_exists(return_file_path.parent) if create_folder else None
+
+        return return_file_path
+
+    @staticmethod
+    def select_folder_location(folder_path: str | None = None, create_folder: bool = False) -> Path | None:
+        """Return an absolute folder path for the given (relative) folder path.
+
+        If folder_path is None, return the project root folder.
+        If folder_path is an absolute path, return it as a Path object.
+        If folder_path is a relative path, return the absolute path based on the project root directory.
+
+        Args:
+            folder_path: The folder path to locate. Can be None, or a relative or absolute path.
+            create_folder: If True, create the folder if it does not exist. Default is False.
+
+        Raises:
+            RuntimeError: If the project root cannot be determined or if folder creation fails.
+
+        Returns:
+            The full path to the folder as a Path object. None if folder_path is None and project root cannot be determined.
+        """
+        try:
+            project_root = SCCommon.get_project_root()
+        except RuntimeError as e:
+            raise RuntimeError(e) from e
+
+        if folder_path is None:
+            return project_root
+
+        selected_folder = Path(folder_path)
+
+        # Check if folder_path is an absolute path, return this even if it does not exist
+        if not selected_folder.is_absolute():
+            selected_folder = (project_root / selected_folder).resolve()
+
+        if create_folder:
+            SCCommon._create_folder_if_not_exists(selected_folder)
+
+        return selected_folder
+
+    @staticmethod
+    def get_process_id() -> int:
+        """Return the process ID of the current process.
+
+        Returns:
+            The process ID of the current process.
+        """
+        return os.getpid()
+
+    @staticmethod
+    def _create_folder_if_not_exists(folder_path: Path) -> None:
+        """Create the folder if it does not exist.
+
+        Args:
+            folder_path: The path of the folder to create.
+
+        Raises:
+            RuntimeError: If folder creation fails.
+        """
+        if not folder_path.exists():
+            try:
+                folder_path.mkdir(parents=True, exist_ok=True)
+            except OSError as e:
+                error_msg = f"Error creating folder '{folder_path}': {e}"
+                raise RuntimeError(error_msg) from e

sc_foundation/sc_config_mgr.py

@@ -0,0 +1,280 @@
+"""Spello Consulting Configuration Manager Module.
+
+Management of a YAML log file.
+"""
+import datetime as dt
+import os
+from collections.abc import Callable
+from pathlib import Path
+
+import yaml
+from cerberus import Validator
+from mergedeep import merge
+
+from sc_foundation.sc_common import SCCommon
+from sc_foundation.sc_date_helper import DateHelper
+from sc_foundation.validation_schema import yaml_config_validation
+
+
+class SCConfigManager:
+    """Loads the configuration from a YAML file, validates it, and provides access to the configuration values."""
+
+    def __init__(self, config_file: str, default_config: dict | None = None, validation_schema: dict | None = None, placeholders: dict | None = None):
+        """Initializes the configuration manager.
+
+        Args:
+            config_file (str): The relative or absolute path to the configuration file.
+            default_config (Optional[dict], optional): A default configuration dict to use if the config file does not exist.
+            validation_schema (Optional[dict], optional): A cerberus style validation schema dict to validate the config file against.
+            placeholders (Optional[dict], optional): A dictionary of placeholders to check in the config. If any of these are found, a exception will be raised.
+
+        Raises:
+            RuntimeError: If the config file does not exist and no default config is provided, or if there are YAML errors in the config file.
+
+        """
+        self._config = {}    # Intialise the actual config object
+        self.config_file = config_file
+        self.logger_function = None  # Placeholder for a logger function
+        self.placeholders = placeholders
+
+        # Build the full validation schema
+        if validation_schema is None:
+            self.validation_schema = yaml_config_validation
+        else:
+            self.validation_schema = merge({}, yaml_config_validation, validation_schema)
+
+        # Determine the file path for the log file
+        self.config_path = SCCommon.select_file_location(self.config_file)
+        if self.config_path is None:
+            msg = f"Cannot find config file {self.config_file}. Please check the path."
+            raise RuntimeError(msg)
+
+        # If the config file doesn't exist and we have a default config, write that to file
+        if not self.config_path.exists():
+            if default_config is None:
+                msg = f"Cannot find config file {self.config_file} and no default config provided."
+                raise RuntimeError(msg)
+
+            with Path(self.config_path).open("w", encoding="utf-8") as file:
+                yaml.dump(default_config, file)
+
+        # Now load the config file
+        self.load_config()
+
+    def load_config(self) -> bool:
+        """Load the configuration from the config file specified to the __init__ method.
+
+        Raises:
+            RuntimeError: If there are YAML errors in the config file, if placeholders are found, or if validation fails.
+
+        Returns:
+            result (bool): True if the configuration was loaded successfully, otherwise False.
+        """
+        if not self.config_path:
+            return False
+
+        with Path(self.config_path).open(encoding="utf-8") as file:
+            try:
+                self._config = yaml.safe_load(file)
+
+            except yaml.YAMLError as e:
+                msg = f"YAML error in config file {self.config_file}: {e}"
+                raise RuntimeError(msg) from e
+
+            else:
+                # Make sure there are no placeholders in the config file, exit if there are
+                self.check_for_placeholders(self.placeholders)
+
+                # If we have a validation schema, validate the config
+                if self.validation_schema is not None:
+                    v = Validator()
+
+                    if not v.validate(self._config, self.validation_schema):  # type: ignore[call-arg]
+                        # Format cerberus errors into human readable lines like "path.to.field: error message"
+
+                        error_lines = self._format_validator_errors(v.errors)  # type: ignore[call-arg]
+                        nice = "\n".join(error_lines)
+                        msg = f"Validation error for config file {self.config_path}: \n{nice}"
+                        raise RuntimeError(msg)
+
+        return True
+
+    @staticmethod
+    def _format_validator_errors(err, path=""):
+        msgs = []
+        # dict: descend into keys
+        if isinstance(err, dict):
+            for k, vv in err.items():
+                new_path = f"{path}: {k}" if path else str(k)
+                msgs.extend(SCConfigManager._format_validator_errors(vv, new_path))
+            return msgs
+        # list: may contain strings or nested dicts (e.g. list of item errors)
+        if isinstance(err, list):
+            for idx, item in enumerate(err):
+                if isinstance(item, (dict, list)):
+                    # for list-items that are dicts, include index in path
+                    if isinstance(item, dict):
+                        new_path = f"{path}" if path else f"[{idx}]"
+                        msgs.extend(SCConfigManager._format_validator_errors(item, new_path))
+                    else:
+                        msgs.extend(SCConfigManager._format_validator_errors(item, path))
+                # item is an error string
+                elif path:
+                    msgs.append(f"{path} - {item}")
+                else:
+                    msgs.append(str(item))
+            return msgs
+        # fallback
+        if path:
+            msgs.append(f"{path}: {err}")
+        else:
+            msgs.append(str(err))
+        return msgs
+
+    def get_config_file_last_modified(self) -> dt.datetime | None:
+        """Get the last modified time of the config file.
+
+        Returns:
+            dt.datetime | None: The last modified time if the config file exists, None otherwise.
+        """
+        if not self.config_path:
+            return None
+
+        return DateHelper.get_file_datetime(self.config_path)
+
+    def check_for_config_changes(self, last_check: dt.datetime) -> dt.datetime | None:
+        """Check if the configuration file has changed. If it has, reload the configuration.
+
+        Args:
+            last_check (dt.datetime): The last time the config was checked.
+
+        Returns:
+            result (dt.datetime | None): The new last modified time if the config has changed and was reloaded, None otherwise.
+        """
+        last_modified_dt = self.get_config_file_last_modified()
+        if last_modified_dt is None:
+            return None
+
+        if last_check is None or last_modified_dt > last_check:
+            # The config file has changed, reload it
+            self.load_config()
+            return last_modified_dt
+
+        return None
+
+    def register_logger(self, logger_function: Callable) -> None:
+        """Registers a logger function to be used for logging messages.
+
+        Args:
+            logger_function (Callable): The function to use for logging messages.
+        """
+        self.logger_function = logger_function
+
+    def check_for_placeholders(self, placeholders: dict | None) -> bool:
+        """Recursively scan self._config for any instances of a key found in placeholders.
+
+        If the keys and values match (including nested), return True.
+
+        Args:
+            placeholders (dict): A dictionary of placeholders to check in the config.
+
+        Raises:
+            RuntimeError: If any placeholder is found in the config file, an exception will be raised with a message indicating the placeholder and its value.
+
+        Returns:
+            result (bool): True if any placeholders are found in the config, otherwise False.
+        """  # noqa: DOC502
+        def recursive_check(config_section, placeholder_section):
+            for key, placeholder_value in placeholder_section.items():
+                if key and key in config_section:
+                    config_value = config_section[key]
+                    if isinstance(placeholder_value, dict) and isinstance(config_value, dict):
+                        if recursive_check(config_value, placeholder_value):
+                            return True
+                    elif config_value == placeholder_value:
+                        msg = f"Placeholder value '{key}: {placeholder_value}' found in config file {self.config_path}. Please fix this."
+                        raise RuntimeError(msg)
+            return False
+
+        if placeholders is None:
+            return False
+
+        return recursive_check(self._config, placeholders)
+
+    def get(self, *keys, default=None):
+        """Retrieve a value from the config dictionary using a sequence of nested keys.
+
+        Example:
+            value = config_mgr.get("DeviceType", "WebsiteAccessKey")
+
+        Args:
+            keys (*keys): Sequence of keys to traverse the config dictionary.
+            default (Optional[variable], optional): Value to return if the key path does not exist.
+
+        Returns:
+            value (variable): The value if found, otherwise the default.
+
+        """
+        value = self._config
+        try:
+            for key in keys:
+                value = value[key]
+        except (KeyError, TypeError):
+            return default
+        else:
+            return value
+
+    def get_logger_settings(self, config_section: str | None = "Files") -> dict:
+        """Returns the logger settings from the config file.
+
+        Args:
+            config_section (Optional[str], optional): The section in the config file where logger settings are stored.
+
+        Returns:
+            settings (dict): A dictionary of logger settings that can be passed to the SCLogger() class initialization.
+        """
+        logger_settings = {
+            "logfile_name": self.get(config_section, "LogfileName"),
+            "file_verbosity": self.get(config_section, "LogfileVerbosity", default="summary"),
+            "console_verbosity": self.get(config_section, "ConsoleVerbosity", default="summary"),
+            "max_lines": self.get(config_section, "LogfileMaxLines", default=10000),
+            "timestamp_format": self.get(config_section, "TimestampFormat", default="%Y-%m-%d %H:%M:%S"),
+            "log_process_id": self.get(config_section, "LogProcessID", default=False),
+            "log_thread_id": self.get(config_section, "LogThreadID", default=False),
+        }
+        return logger_settings
+
+    def get_email_settings(self, config_section: str | None = "Email") -> dict | None:
+        """Returns the email settings from the config file.
+
+        Args:
+            config_section (Optional[str], optional): The section in the config file where email settings are stored.
+
+        Returns:
+            settings (dict): A dictionary of email settings or None if email is disabled or not configured correctly.
+        """
+        # fir check to see if we have an EnableEmail setting
+        enable_email = self.get(config_section, "EnableEmail", default=True)
+        if not enable_email:
+            return None
+        smtp_username = os.environ.get("SMTP_USERNAME")
+        if not smtp_username:
+            smtp_username = self.get(config_section, "SMTPUsername")
+        smtp_password = os.environ.get("SMTP_PASSWORD")
+        if not smtp_password:
+            smtp_password = self.get(config_section, "SMTPPassword")
+
+        email_settings = {
+            "SendEmailsTo": self.get(config_section, "SendEmailsTo"),
+            "SMTPServer": self.get(config_section, "SMTPServer"),
+            "SMTPUsername": smtp_username,
+            "SMTPPassword": smtp_password,
+            "SubjectPrefix": self.get(config_section, "SubjectPrefix"),
+        }
+
+        # Only return true if all the required email settings have been specified (excluding SubjectPrefix)
+        required_fields = {k: v for k, v in email_settings.items() if k != "SubjectPrefix"}
+        if all(required_fields.values()):
+            return email_settings
+
+        return None