Merge pull request #25 from MScottBlake/refactor-appconfig

Replace `AppConfig` with `settings`

Author: MScottBlake

pyproject.toml

@@ -14,7 +14,7 @@ dev = [
 
 [project]
 name = "cloud-autopkg-runner"
-version = "0.10.0"
+version = "0.11.0"
 description = "A Python library designed to level-up your AutoPkg automations with a focus on CI/CD performance."
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.10"

src/cloud_autopkg_runner/__init__.py

@@ -13,159 +13,8 @@
 - Metadata caching to reduce redundant downloads.
 """
 
-from pathlib import Path
+from .settings import settings
 
-
-class AppConfig:
-    """Manages application-wide configuration settings.
-
-    This class uses class variables to store configuration data and
-    class methods to manage and access that data. It provides access
-    to configuration parameters such as verbosity level, log file path,
-    and the metadata cache file path.
-    """
-
-    _cache_file: Path = Path("metadata_cache.json")
-    _log_file: Path | None = None
-    _max_concurrency: int = 10
-    _report_dir: Path = Path("recipe_reports")
-    _verbosity_level: int = 0
-
-    @classmethod
-    def set_config(
-        cls,
-        *,
-        max_concurrency: int | None = None,
-        verbosity_level: int | None = None,
-        cache_file: Path | None = None,
-        report_dir: Path | None = None,
-        log_file: Path | None = None,
-    ) -> None:
-        """Set the application configuration parameters.
-
-        This method updates the class variables that store the verbosity
-        level, log file path, and cache file path. It does *not* initialize
-        the logging system; `initialize_logger()` must be called separately.
-
-        Args:
-            verbosity_level: The integer verbosity level (0, 1, 2, etc.).
-            max_concurrency: The integer concurrency limit.
-            log_file: Optional path to the log file. If specified, logging
-                output will be written to this file in addition to the console.
-            cache_file: The path to the cache file.
-            report_dir: The path to the directory used for storing AutoPkg recipe
-                recipts and recipe reports.
-        """
-        if verbosity_level is not None:
-            cls._verbosity_level = verbosity_level
-
-        if log_file is not None:
-            cls._log_file = log_file
-
-        if cache_file is not None:
-            cls._cache_file = cache_file
-
-        if max_concurrency is not None:
-            cls._max_concurrency = max_concurrency
-
-        if report_dir is not None:
-            cls._report_dir = report_dir
-
-    @classmethod
-    def cache_file(cls) -> Path:
-        """Returns the path to the metadata cache file."""
-        return cls._cache_file
-
-    @classmethod
-    def log_file(cls) -> Path | None:
-        """Returns the path to the log file, if any.
-
-        Returns:
-            The path to the log file as a `pathlib.Path`, or None if no log file is
-            configured.
-        """
-        return cls._log_file
-
-    @classmethod
-    def report_dir(cls) -> Path:
-        """Returns the directory path for recipe reports.
-
-        Returns:
-            The path to the report directory as a `pathlib.Path`.
-        """
-        return cls._report_dir
-
-    @classmethod
-    def max_concurrency(cls) -> int:
-        """Returns the maximum number of concurrent tasks.
-
-        Returns:
-            Returns the maximum number of concurrent tasks as an integer.
-        """
-        return cls._max_concurrency
-
-    @classmethod
-    def verbosity_int(cls, delta: int = 0) -> int:
-        """Returns the verbosity level.
-
-        Args:
-            delta: An optional integer to add to the base verbosity level.
-                This can be used to temporarily increase or decrease the
-                verbosity for specific operations.
-
-        Returns:
-            The integer verbosity level, adjusted by the delta.
-        """
-        level = cls._verbosity_level + delta
-        if level <= 0:
-            return 0
-        return level
-
-    @classmethod
-    def verbosity_str(cls, delta: int = 0) -> str:
-        """Convert an integer verbosity level to a string of `-v` flags.
-
-        Args:
-            delta: An optional integer to add to the base verbosity level.
-                This can be used to temporarily increase or decrease the
-                verbosity for specific operations.
-
-        Returns:
-            A string consisting of `-` followed by `v` repeated `verbosity_level`
-            times. Returns an empty string if verbosity_level is 0 or negative.
-
-        Examples:
-            verbosity_str(0) == ""
-            verbosity_str(1) == "-v"
-            verbosity_str(2) == "-vv"
-            verbosity_str(3) == "-vvv"
-        """
-        level = cls._verbosity_level + delta
-        if level <= 0:
-            return ""
-        return "-" + "v" * level
-
-
-# Located here to prevent circular imports
-def list_possible_file_names(recipe_name: str) -> list[str]:
-    """Generate a list of possible AutoPkg recipe file names.
-
-    Given a recipe name, this function returns a list of possible file names
-    by appending common AutoPkg recipe file extensions. If the recipe name
-    already ends with a known extension, it returns a list containing only the
-    original recipe name.
-
-    Args:
-        recipe_name: The name of the AutoPkg recipe.
-
-    Returns:
-        A list of possible file names for the recipe.
-    """
-    if recipe_name.endswith((".recipe", ".recipe.plist", ".recipe.yaml")):
-        return [recipe_name]
-
-    return [
-        recipe_name + ".recipe",
-        recipe_name + ".recipe.plist",
-        recipe_name + ".recipe.yaml",
-    ]
+__all__ = [
+    "settings",
+]

src/cloud_autopkg_runner/__main__.py

@@ -24,7 +24,7 @@
 from types import FrameType
 from typing import NoReturn
 
-from cloud_autopkg_runner import AppConfig
+from cloud_autopkg_runner import settings
 from cloud_autopkg_runner.exceptions import (
     InvalidFileContents,
     InvalidJsonContents,
@@ -152,15 +152,13 @@ async def _process_recipe_list(
     logger = get_logger(__name__)
     logger.debug("Processing recipes...")
 
-    report_dir = AppConfig.report_dir()
-
     recipes: list[Recipe] = []
     for recipe_name in recipe_list:
         with contextlib.suppress(InvalidFileContents, RecipeException):
-            recipes.append(Recipe(recipe_name, report_dir))  # Skips failures
+            recipes.append(Recipe(recipe_name, settings.report_dir))  # Skips failures
 
     async def run_limited(recipe: Recipe) -> tuple[str, ConsolidatedReport]:
-        async with asyncio.Semaphore(AppConfig.max_concurrency()):  # Limit concurrency
+        async with asyncio.Semaphore(settings.max_concurrency):  # Limit concurrency
             return recipe.name, await recipe.run()
 
     results = await asyncio.gather(*[run_limited(recipe) for recipe in recipes])
@@ -202,13 +200,11 @@ async def _async_main() -> None:
     args = _parse_arguments()
     initialize_logger(args.verbose, args.log_file)
 
-    AppConfig.set_config(
-        cache_file=args.cache_file,
-        log_file=args.log_file,
-        max_concurrency=args.max_concurrency,
-        report_dir=args.report_dir,
-        verbosity_level=args.verbose,
-    )
+    settings.cache_file = args.cache_file
+    settings.log_file = args.log_file
+    settings.max_concurrency = args.max_concurrency
+    settings.report_dir = args.report_dir
+    settings.verbosity_level = args.verbose
 
     recipe_list = _generate_recipe_list(args)
 

src/cloud_autopkg_runner/common_utils.py

@@ -0,0 +1,35 @@
+"""Provides common utility functions for cloud-autopkg-runner.
+
+This module encapsulates general-purpose utility functions that are
+used throughout the cloud-autopkg-runner project.  Currently, it includes
+a function for generating a list of possible AutoPkg recipe file names
+based on common naming conventions.
+
+Functions:
+    list_possible_file_names: Generates a list of possible AutoPkg recipe
+        file names for a given recipe name.
+"""
+
+
+def list_possible_file_names(recipe_name: str) -> list[str]:
+    """Generate a list of possible AutoPkg recipe file names.
+
+    Given a recipe name, this function returns a list of possible file names
+    by appending common AutoPkg recipe file extensions. If the recipe name
+    already ends with a known extension, it returns a list containing only the
+    original recipe name.
+
+    Args:
+        recipe_name: The name of the AutoPkg recipe.
+
+    Returns:
+        A list of possible file names for the recipe.
+    """
+    if recipe_name.endswith((".recipe", ".recipe.plist", ".recipe.yaml")):
+        return [recipe_name]
+
+    return [
+        recipe_name + ".recipe",
+        recipe_name + ".recipe.plist",
+        recipe_name + ".recipe.yaml",
+    ]

src/cloud_autopkg_runner/exceptions.py

@@ -144,6 +144,23 @@ def __init__(self, recipe_extension: str) -> None:
         super().__init__(f"Invalid recipe format: {recipe_extension}")
 
 
+# Settings
+class SettingsValidationError(AutoPkgRunnerException):
+    """Exception class for handling validation errors in Settings.
+
+    This exception is raised when a Setting value does not validate successfully.
+    """
+
+    def __init__(self, field_name: str, validation_error: str) -> None:
+        """Initializes SettingsValidationError with the invalid file extension.
+
+        Args:
+            field_name: The name of the invalid Setting.
+            validation_error: The message explaining the failure.
+        """
+        super().__init__(f"Invalid value for '{field_name}': {validation_error}")
+
+
 # Shell Command
 class ShellCommandException(AutoPkgRunnerException):
     """Base exception class for handling issues with shell commands.

src/cloud_autopkg_runner/file_utils.py

@@ -22,7 +22,7 @@
 
 import xattr  # pyright: ignore[reportMissingTypeStubs]
 
-from cloud_autopkg_runner import list_possible_file_names
+from cloud_autopkg_runner.common_utils import list_possible_file_names
 from cloud_autopkg_runner.logging_config import get_logger
 from cloud_autopkg_runner.metadata_cache import DownloadMetadata, MetadataCache
 

src/cloud_autopkg_runner/metadata_cache.py

@@ -135,6 +135,7 @@ def _load_from_disk(file_path: Path) -> MetadataCache:
         if not file_path.exists():
             logger = get_logger(__name__)
             logger.warning("%s does not exist. Creating...", file_path)
+            file_path.parent.mkdir(parents=True, exist_ok=True)
             file_path.write_text("{}")
             logger.info("%s created.", file_path)
 

src/cloud_autopkg_runner/recipe.py

@@ -21,7 +21,7 @@
 
 import yaml
 
-from cloud_autopkg_runner import AppConfig
+from cloud_autopkg_runner import settings
 from cloud_autopkg_runner.autopkg_prefs import AutoPkgPrefs
 from cloud_autopkg_runner.exceptions import (
     InvalidPlistContents,
@@ -102,7 +102,7 @@ def __init__(self, recipe_name: str, report_dir: Path | None = None) -> None:
         Args:
             recipe_name: Name of the recipe file.
             report_dir: Path to the report directory. If None, a the value returned
-                from `AppConfig.report_dir()` is used.
+                from `settings.report_dir` is used.
         """
         self._name: str = recipe_name
 
@@ -119,7 +119,7 @@ def __init__(self, recipe_name: str, report_dir: Path | None = None) -> None:
 
         now_str = datetime.now(tz=timezone.utc).strftime("%y%m%d_%H%M")
         if report_dir is None:
-            report_dir = AppConfig.report_dir()
+            report_dir = settings.report_dir
         report_path: Path = report_dir / f"report_{now_str}_{self.name}.plist"
 
         counter = 1
@@ -278,8 +278,8 @@ def _autopkg_run_cmd(self, *, check: bool = False) -> list[str]:
             f"--report-plist={self._result.file_path()}",
         ]
 
-        if AppConfig.verbosity_int(-1) > 0:
-            cmd.append(AppConfig.verbosity_str(-1))
+        if settings.verbosity_int(-1) > 0:
+            cmd.append(settings.verbosity_str(-1))
 
         if check:
             cmd.append("--check")
@@ -460,7 +460,7 @@ async def run(self) -> ConsolidatedReport:
         output = await self.run_check_phase()
         if output["downloaded_items"]:
             metadata = await self._get_metadata(output["downloaded_items"])
-            await MetadataCacheManager.save(AppConfig.cache_file(), self.name, metadata)
+            await MetadataCacheManager.save(settings.cache_file, self.name, metadata)
 
             return await self.run_full()
         return output
@@ -570,8 +570,8 @@ async def verify_trust_info(self) -> bool:
                 f"--override-dir={self._path.parent}",
             ]
 
-            if AppConfig.verbosity_int() > 0:
-                cmd.append(AppConfig.verbosity_str())
+            if settings.verbosity_int() > 0:
+                cmd.append(settings.verbosity_str())
 
             returncode, _stdout, _stderr = await run_cmd(cmd, check=False)