fmu-settings 0.5.2__py3-none-any.whl → 0.14.1__py3-none-any.whl

fmu/settings/_fmu_dir.py

@@ -1,14 +1,18 @@
 """Main interface for working with .fmu directory."""
 
 from pathlib import Path
-from typing import Any, Final, Self, TypeAlias, cast
+from typing import TYPE_CHECKING, Any, Final, Self, TypeAlias, cast
+
+from fmu.settings._resources.changelog_manager import ChangelogManager
 
 from ._logging import null_logger
+from ._readme_texts import PROJECT_README_CONTENT, USER_README_CONTENT
+from ._resources.cache_manager import CacheManager
 from ._resources.config_managers import (
     ProjectConfigManager,
     UserConfigManager,
 )
-from ._resources.lock_manager import LockManager
+from ._resources.lock_manager import DEFAULT_LOCK_TIMEOUT, LockManager
 from .models.project_config import ProjectConfig
 from .models.user_config import UserConfig
 
@@ -22,13 +26,24 @@ class FMUDirectoryBase:
 
     config: FMUConfigManager
     _lock: LockManager
-
-    def __init__(self: Self, base_path: str | Path) -> None:
+    _cache_manager: CacheManager
+    _README_CONTENT: str = ""
+    _changelog: ChangelogManager
+
+    def __init__(
+        self: Self,
+        base_path: str | Path,
+        cache_revisions: int = CacheManager.MIN_REVISIONS,
+        *,
+        lock_timeout_seconds: int = DEFAULT_LOCK_TIMEOUT,
+    ) -> None:
         """Initializes access to a .fmu directory.
 
         Args:
             base_path: The directory containing the .fmu directory or one of its parent
                 dirs
+            cache_revisions: Number of revisions to retain in the cache. Minimum is 5.
+            lock_timeout_seconds: Lock expiration time in seconds. Default 20 minutes.
 
         Raises:
             FileExistsError: If .fmu exists but is not a directory
@@ -37,7 +52,9 @@ class FMUDirectoryBase:
         """
         self.base_path = Path(base_path).resolve()
         logger.debug(f"Initializing FMUDirectory from '{base_path}'")
-        self._lock = LockManager(self)
+        self._lock = LockManager(self, timeout_seconds=lock_timeout_seconds)
+        self._cache_manager = CacheManager(self, max_revisions=cache_revisions)
+        self._changelog = ChangelogManager(self)
 
         fmu_dir = self.base_path / ".fmu"
         if fmu_dir.exists():
@@ -57,6 +74,28 @@ class FMUDirectoryBase:
         """Returns the path to the .fmu directory."""
         return self._path
 
+    @property
+    def cache(self: Self) -> CacheManager:
+        """Access the cache manager."""
+        return self._cache_manager
+
+    @property
+    def cache_max_revisions(self: Self) -> int:
+        """Current retention limit for revision snapshots."""
+        return self._cache_manager.max_revisions
+
+    @cache_max_revisions.setter
+    def cache_max_revisions(self: Self, value: int) -> None:
+        """Update the retention limit for revision snapshots.
+
+        Args:
+            value: The new maximum number of revisions to retain. Minimum value is 5.
+                Values below 5 are set to 5.
+        """
+        clamped_value = max(CacheManager.MIN_REVISIONS, value)
+        self._cache_manager.max_revisions = clamped_value
+        self.set_config_value("cache_max_revisions", clamped_value)
+
     def get_config_value(self: Self, key: str, default: Any = None) -> Any:
         """Gets a configuration value by key.
 
@@ -212,14 +251,59 @@ class FMUDirectoryBase:
         """
         return self.get_file_path(relative_path).exists()
 
+    def restore(self: Self) -> None:
+        """Attempt to reconstruct missing .fmu files from in-memory state."""
+        if not self.path.exists():
+            self.path.mkdir(parents=True, exist_ok=True)
+            logger.info("Recreated missing .fmu directory at %s", self.path)
+
+        readme_path = self.get_file_path("README")
+        if self._README_CONTENT and not readme_path.exists():
+            self.write_text_file("README", self._README_CONTENT)
+            logger.info("Restored README at %s", readme_path)
+
+        config_path = self.config.path
+        if not config_path.exists():
+            cached_model = getattr(self.config, "_cache", None)
+            if cached_model is not None:
+                self.config.save(cached_model)
+                logger.info("Restored config.json from cached model at %s", config_path)
+            else:
+                self.config.reset()
+                logger.info("Restored config.json from defaults at %s", config_path)
+
 
 class ProjectFMUDirectory(FMUDirectoryBase):
-    config: ProjectConfigManager
+    if TYPE_CHECKING:
+        config: ProjectConfigManager
+
+    _README_CONTENT: str = PROJECT_README_CONTENT
+
+    def __init__(
+        self: Self,
+        base_path: str | Path,
+        *,
+        lock_timeout_seconds: int = DEFAULT_LOCK_TIMEOUT,
+    ) -> None:
+        """Initializes a project-based .fmu directory.
 
-    def __init__(self, base_path: str | Path) -> None:
-        """Initializes a project-based .fmu directory."""
+        Args:
+            base_path: Project directory containing the .fmu folder.
+            lock_timeout_seconds: Lock expiration time in seconds. Default 20 minutes.
+        """
         self.config = ProjectConfigManager(self)
-        super().__init__(base_path)
+        super().__init__(
+            base_path,
+            CacheManager.MIN_REVISIONS,
+            lock_timeout_seconds=lock_timeout_seconds,
+        )
+        try:
+            max_revisions = self.config.get(
+                "cache_max_revisions", CacheManager.MIN_REVISIONS
+            )
+            self._cache_manager.max_revisions = max_revisions
+        except FileNotFoundError:
+            pass
 
     def update_config(self: Self, updates: dict[str, Any]) -> ProjectConfig:
         """Updates multiple configuration values at once.
@@ -267,11 +351,17 @@ class ProjectFMUDirectory(FMUDirectoryBase):
         return None
 
     @classmethod
-    def find_nearest(cls: type[Self], start_path: str | Path = ".") -> Self:
+    def find_nearest(
+        cls: type[Self],
+        start_path: str | Path = ".",
+        *,
+        lock_timeout_seconds: int = DEFAULT_LOCK_TIMEOUT,
+    ) -> Self:
         """Factory method to find and open the nearest .fmu directory.
 
         Args:
             start_path: Path to start searching from. Default current working director
+            lock_timeout_seconds: Lock expiration time in seconds. Default 20 minutes.
 
         Returns:
             FMUDirectory instance
@@ -283,16 +373,146 @@ class ProjectFMUDirectory(FMUDirectoryBase):
         fmu_dir_path = cls.find_fmu_directory(start_path)
         if fmu_dir_path is None:
             raise FileNotFoundError(f"No .fmu directory found at or above {start_path}")
-        return cls(fmu_dir_path.parent)
+        return cls(fmu_dir_path.parent, lock_timeout_seconds=lock_timeout_seconds)
+
+    def find_rms_projects(self: Self) -> list[Path]:
+        """Searches for RMS project directories under the project root.
+
+        RMS projects are identified by the presence of both .master and rms.ini
+        files within a directory under rms/model/.
+
+        Returns:
+            List of Path objects to RMS project directories, sorted alphabetically.
+            Returns empty list if none found.
+        """
+        project_root = self.base_path
+        model_root = project_root / "rms/model"
+        rms_projects: set[Path] = set()
+
+        if model_root.is_dir():
+            for candidate in model_root.iterdir():
+                if not candidate.is_dir():
+                    continue
+
+                master_file = candidate / ".master"
+                ini_file = candidate / "rms.ini"
+
+                if master_file.is_file() and ini_file.is_file():
+                    rms_projects.add(candidate)
+
+        return sorted(rms_projects)
+
+    def _sync_runtime_variables(self: Self) -> None:
+        """Sync runtime variables with config file."""
+        max_revisions_from_config = self.config.load().cache_max_revisions
+        if self._cache_manager.max_revisions != max_revisions_from_config:
+            self._cache_manager.max_revisions = max_revisions_from_config
+
+    def get_dir_diff(
+        self: Self, new_fmu_dir: Self
+    ) -> dict[str, list[tuple[str, Any, Any]]]:
+        """Get the resource differences between two .fmu directories.
+
+        Compare all resources in the two .fmu directories and return a dict with the
+        diff for each resource.
+
+        Resources that are not present in both .fmu directories will not be diffed.
+        """
+        dir_diff: dict[str, list[tuple[str, Any, Any]]] = {}
+
+        for resource in vars(self):
+            try:
+                match resource:
+                    case "config":
+                        current_resource: ProjectConfigManager = getattr(self, resource)
+                        new_resource: ProjectConfigManager = getattr(
+                            new_fmu_dir, resource
+                        )
+                        changes = current_resource.get_resource_diff(new_resource)
+                    case "_changelog":
+                        current_changelog: ChangelogManager = getattr(self, resource)
+                        new_changelog: ChangelogManager = getattr(new_fmu_dir, resource)
+                        changelog_diff = current_changelog.get_changelog_diff(
+                            new_changelog
+                        )
+                        if len(changelog_diff.root) > 0:
+                            changes = [("changelog", None, changelog_diff)]
+                        else:
+                            changes = []
+
+                    case _:
+                        continue
+            except AttributeError:
+                continue
+            except FileNotFoundError:
+                continue
+
+            dir_diff[resource] = changes
+        return dir_diff
+
+    def sync_dir(self: Self, new_fmu_dir: Self) -> dict[str, Any]:
+        """Sync the resources in two .fmu directories.
+
+        Compare all resources in the two .fmu directories and merge all changes
+        in the new .fmu directory into the current .fmu directory.
+
+        Resources that are not present in both .fmu directories will not be synced.
+        """
+        changes_in_dir = self.get_dir_diff(new_fmu_dir)
+        updates: dict[str, Any] = {}
+        for resource, changes in changes_in_dir.items():
+            if len(changes) == 0:
+                continue
+
+            updated_resource: Any
+            if resource == "config":
+                current_config: ProjectConfigManager = getattr(self, resource)
+                updated_resource = current_config.merge_changes(changes)
+                self._sync_runtime_variables()
+            elif resource == "_changelog":
+                current_changelog: ChangelogManager = getattr(self, resource)
+                updated_resource = current_changelog.merge_changes(changes[0][2].root)
+
+            updates[resource] = updated_resource
+
+        self._changelog.log_merge_to_changelog(
+            source_path=self.path,
+            incoming_path=new_fmu_dir.path,
+            merged_resources=list(updates.keys()),
+        )
+
+        return updates
 
 
 class UserFMUDirectory(FMUDirectoryBase):
-    config: UserConfigManager
+    if TYPE_CHECKING:
+        config: UserConfigManager
 
-    def __init__(self) -> None:
-        """Initializes a project-based .fmu directory."""
+    _README_CONTENT: str = USER_README_CONTENT
+
+    def __init__(
+        self: Self,
+        *,
+        lock_timeout_seconds: int = DEFAULT_LOCK_TIMEOUT,
+    ) -> None:
+        """Initializes a user .fmu directory.
+
+        Args:
+            lock_timeout_seconds: Lock expiration time in seconds. Default 20 minutes.
+        """
         self.config = UserConfigManager(self)
-        super().__init__(Path.home())
+        super().__init__(
+            Path.home(),
+            CacheManager.MIN_REVISIONS,
+            lock_timeout_seconds=lock_timeout_seconds,
+        )
+        try:
+            max_revisions = self.config.get(
+                "cache_max_revisions", CacheManager.MIN_REVISIONS
+            )
+            self._cache_manager.max_revisions = max_revisions
+        except FileNotFoundError:
+            pass
 
     def update_config(self: Self, updates: dict[str, Any]) -> UserConfig:
         """Updates multiple configuration values at once.
@@ -310,12 +530,17 @@ class UserFMUDirectory(FMUDirectoryBase):
         return cast("UserConfig", super().update_config(updates))
 
 
-def get_fmu_directory(base_path: str | Path) -> ProjectFMUDirectory:
+def get_fmu_directory(
+    base_path: str | Path,
+    *,
+    lock_timeout_seconds: int = DEFAULT_LOCK_TIMEOUT,
+) -> ProjectFMUDirectory:
     """Initializes access to a .fmu directory.
 
     Args:
         base_path: The directory containing the .fmu directory or one of its parent
                    dirs
+        lock_timeout_seconds: Lock expiration time in seconds. Default 20 minutes.
 
     Returns:
         FMUDirectory instance
@@ -326,14 +551,19 @@ def get_fmu_directory(base_path: str | Path) -> ProjectFMUDirectory:
         PermissionError: If lacking permissions to read/write to the directory
 
     """
-    return ProjectFMUDirectory(base_path)
+    return ProjectFMUDirectory(base_path, lock_timeout_seconds=lock_timeout_seconds)
 
 
-def find_nearest_fmu_directory(start_path: str | Path = ".") -> ProjectFMUDirectory:
+def find_nearest_fmu_directory(
+    start_path: str | Path = ".",
+    *,
+    lock_timeout_seconds: int = DEFAULT_LOCK_TIMEOUT,
+) -> ProjectFMUDirectory:
     """Factory method to find and open the nearest .fmu directory.
 
     Args:
         start_path: Path to start searching from. Default current working directory
+        lock_timeout_seconds: Lock expiration time in seconds. Default 20 minutes.
 
     Returns:
         FMUDirectory instance
@@ -341,4 +571,6 @@ def find_nearest_fmu_directory(start_path: str | Path = ".") -> ProjectFMUDirect
     Raises:
         FileNotFoundError: If no .fmu directory is found
     """
-    return ProjectFMUDirectory.find_nearest(start_path)
+    return ProjectFMUDirectory.find_nearest(
+        start_path, lock_timeout_seconds=lock_timeout_seconds
+    )

fmu/settings/_init.py

@@ -1,43 +1,18 @@
 """Initializes the .fmu directory."""
 
 from pathlib import Path
-from textwrap import dedent
 from typing import Any, Final
 
 from fmu.datamodels.fmu_results.global_configuration import GlobalConfiguration
 
 from ._fmu_dir import ProjectFMUDirectory, UserFMUDirectory
 from ._logging import null_logger
+from ._readme_texts import PROJECT_README_CONTENT, USER_README_CONTENT
+from ._resources.lock_manager import DEFAULT_LOCK_TIMEOUT
 from .models.project_config import ProjectConfig
 
 logger: Final = null_logger(__name__)
 
-_README = dedent("""\
-    This directory contains static configuration data for your FMU project.
-
-    You should *not* manually modify files within this directory. Doing so may
-    result in erroneous behavior or erroneous data in your FMU project.
-
-    Changes to data stored within this directory must happen through the FMU
-    Settings application.
-
-    Run `fmu-settings` to do this.
-""")
-
-_USER_README = dedent("""\
-    This directory contains static data and configuration elements used by some
-    components in FMU. It may also contains sensitive access tokens that should not be
-    shared with others.
-
-    You should *not* manually modify files within this directory. Doing so may
-    result in erroneous behavior by some FMU components.
-
-    Changes to data stored within this directory must happen through the FMU
-    Settings application.
-
-    Run `fmu-settings` to do this.
-""")
-
 
 def _create_fmu_directory(base_path: Path) -> None:
     """Creates the .fmu directory.
@@ -71,6 +46,8 @@ def init_fmu_directory(
     base_path: str | Path,
     config_data: ProjectConfig | dict[str, Any] | None = None,
     global_config: GlobalConfiguration | None = None,
+    *,
+    lock_timeout_seconds: int = DEFAULT_LOCK_TIMEOUT,
 ) -> ProjectFMUDirectory:
     """Creates and initializes a .fmu directory.
 
@@ -83,6 +60,7 @@ def init_fmu_directory(
           data.
         global_config: Optional GlobaConfiguration instance with existing global config
           data.
+        lock_timeout_seconds: Lock expiration time in seconds. Default 20 minutes.
 
     Returns:
         Instance of FMUDirectory
@@ -98,8 +76,11 @@ def init_fmu_directory(
 
     _create_fmu_directory(base_path)
 
-    fmu_dir = ProjectFMUDirectory(base_path)
-    fmu_dir.write_text_file("README", _README)
+    fmu_dir = ProjectFMUDirectory(
+        base_path,
+        lock_timeout_seconds=lock_timeout_seconds,
+    )
+    fmu_dir.write_text_file("README", PROJECT_README_CONTENT)
 
     fmu_dir.config.reset()
     if config_data:
@@ -115,9 +96,15 @@ def init_fmu_directory(
     return fmu_dir
 
 
-def init_user_fmu_directory() -> UserFMUDirectory:
+def init_user_fmu_directory(
+    *,
+    lock_timeout_seconds: int = DEFAULT_LOCK_TIMEOUT,
+) -> UserFMUDirectory:
     """Creates and initializes a user's $HOME/.fmu directory.
 
+    Args:
+        lock_timeout_seconds: Lock expiration time in seconds. Default 20 minutes.
+
     Returns:
         Instance of FMUDirectory
 
@@ -131,8 +118,8 @@ def init_user_fmu_directory() -> UserFMUDirectory:
 
     _create_fmu_directory(Path.home())
 
-    fmu_dir = UserFMUDirectory()
-    fmu_dir.write_text_file("README", _USER_README)
+    fmu_dir = UserFMUDirectory(lock_timeout_seconds=lock_timeout_seconds)
+    fmu_dir.write_text_file("README", USER_README_CONTENT)
 
     fmu_dir.config.reset()
     logger.debug(f"Successfully initialized .fmu directory at '{fmu_dir}'")

fmu/settings/_readme_texts.py

@@ -0,0 +1,34 @@
+"""Shared README content for .fmu directories."""
+
+from textwrap import dedent
+from typing import Final
+
+PROJECT_README_CONTENT: Final[str] = dedent(
+    """\
+    This directory contains static configuration data for your FMU project.
+
+    You should *not* manually modify files within this directory. Doing so may
+    result in erroneous behavior or erroneous data in your FMU project.
+
+    Changes to data stored within this directory must happen through the FMU
+    Settings application.
+
+    Run `fmu settings` to do this.
+    """
+)
+
+USER_README_CONTENT: Final[str] = dedent(
+    """\
+    This directory contains static data and configuration elements used by some
+    components in FMU. It may also contains sensitive access tokens that should not be
+    shared with others.
+
+    You should *not* manually modify files within this directory. Doing so may
+    result in erroneous behavior by some FMU components.
+
+    Changes to data stored within this directory must happen through the FMU
+    Settings application.
+
+    Run `fmu settings` to do this.
+    """
+)

fmu/settings/_resources/cache_manager.py

@@ -0,0 +1,185 @@
+"""Utilities for storing revision snapshots of .fmu files."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import TYPE_CHECKING, ClassVar, Final, Self
+from uuid import uuid4
+
+from fmu.settings._logging import null_logger
+
+if TYPE_CHECKING:
+    from fmu.settings._fmu_dir import FMUDirectoryBase
+
+logger: Final = null_logger(__name__)
+
+_CACHEDIR_TAG_CONTENT: Final = (
+    "Signature: 8a477f597d28d172789f06886806bc55\n"
+    "# This directory contains cached FMU files.\n"
+    "# For information about cache directory tags, see:\n"
+    "#	https://bford.info/cachedir/spec.html"
+)
+
+
+class CacheManager:
+    """Stores complete file revisions under the `.fmu/cache` tree."""
+
+    MIN_REVISIONS: ClassVar[int] = 5
+    RETENTION_DAYS: ClassVar[int] = 30
+
+    def __init__(
+        self: Self,
+        fmu_dir: FMUDirectoryBase,
+        max_revisions: int = 5,
+    ) -> None:
+        """Initialize the cache manager.
+
+        Args:
+            fmu_dir: The FMUDirectory instance.
+            max_revisions: Maximum number of revisions to retain. Default is 5.
+                Values below 5 are set to 5.
+        """
+        self._fmu_dir = fmu_dir
+        self._cache_root = Path("cache")
+        self._max_revisions = max(self.MIN_REVISIONS, max_revisions)
+
+    @property
+    def max_revisions(self: Self) -> int:
+        """Maximum number of revisions retained per resource."""
+        return self._max_revisions
+
+    @max_revisions.setter
+    def max_revisions(self: Self, value: int) -> None:
+        """Update the per-resource revision retention.
+
+        Args:
+            value: The new maximum number of revisions. Minimum value is 5.
+                Values below 5 are set to 5.
+        """
+        self._max_revisions = max(self.MIN_REVISIONS, value)
+
+    def store_revision(
+        self: Self,
+        resource_file_path: Path | str,
+        content: str,
+        encoding: str = "utf-8",
+        skip_trim: bool = False,
+    ) -> Path | None:
+        """Write a full snapshot of the resource file to the cache directory.
+
+        Args:
+            resource_file_path: Relative path within the ``.fmu`` directory (e.g.,
+                ``config.json``) of the resource file being cached.
+            content: Serialized payload to store.
+            encoding: Encoding used when persisting the snapshot. Defaults to UTF-8.
+            skip_trim: If True, skip count-based trimming. Default is False.
+
+        Returns:
+            Absolute filesystem path to the stored snapshot.
+        """
+        resource_file_path = Path(resource_file_path)
+        cache_dir = self._ensure_resource_cache_dir(resource_file_path)
+        snapshot_name = self._snapshot_filename(resource_file_path)
+        snapshot_path = cache_dir / snapshot_name
+
+        cache_relative = self._cache_root / resource_file_path.stem
+        self._fmu_dir.write_text_file(
+            cache_relative / snapshot_name, content, encoding=encoding
+        )
+        logger.debug("Stored revision snapshot at %s", snapshot_path)
+
+        if not skip_trim:
+            self._trim(cache_dir)
+        return snapshot_path
+
+    def list_revisions(self: Self, resource_file_path: Path | str) -> list[Path]:
+        """List existing snapshots for a resource file, sorted oldest to newest.
+
+        Args:
+            resource_file_path: Relative path within the ``.fmu`` directory (e.g.,
+                ``config.json``) whose cache entries should be listed.
+
+        Returns:
+            A list of absolute `Path` objects sorted oldest to newest.
+        """
+        resource_file_path = Path(resource_file_path)
+        cache_relative = self._cache_root / resource_file_path.stem
+        if not self._fmu_dir.file_exists(cache_relative):
+            return []
+        cache_dir = self._fmu_dir.get_file_path(cache_relative)
+
+        revisions = [p for p in cache_dir.iterdir() if p.is_file()]
+        revisions.sort(key=lambda path: path.name)
+        return revisions
+
+    def _ensure_resource_cache_dir(self: Self, resource_file_path: Path) -> Path:
+        """Create (if needed) and return the cache directory for resource file."""
+        self._cache_root_path(create=True)
+        resource_cache_dir_relative = self._cache_root / resource_file_path.stem
+        return self._fmu_dir.ensure_directory(resource_cache_dir_relative)
+
+    def _cache_root_path(self: Self, create: bool) -> Path:
+        """Resolve the cache root, creating it and the cachedir tag if requested."""
+        if create:
+            cache_root = self._fmu_dir.ensure_directory(self._cache_root)
+            self._ensure_cachedir_tag()
+            return cache_root
+
+        return self._fmu_dir.get_file_path(self._cache_root)
+
+    def _ensure_cachedir_tag(self: Self) -> None:
+        """Ensure the cache root complies with the Cachedir specification."""
+        tag_path_relative = self._cache_root / "CACHEDIR.TAG"
+        if self._fmu_dir.file_exists(tag_path_relative):
+            return
+        self._fmu_dir.write_text_file(tag_path_relative, _CACHEDIR_TAG_CONTENT)
+
+    def _snapshot_filename(self: Self, resource_file_path: Path) -> str:
+        """Generate a timestamped filename for the next snapshot."""
+        timestamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%S.%fZ")
+        suffix = resource_file_path.suffix or ".txt"
+        token = uuid4().hex[:8]
+        return f"{timestamp}-{token}{suffix}"
+
+    def _trim(self: Self, cache_dir: Path) -> None:
+        """Remove the oldest snapshots until the retention limit is respected."""
+        revisions = [p for p in cache_dir.iterdir() if p.is_file()]
+        if len(revisions) <= self.max_revisions:
+            return
+
+        revisions.sort(key=lambda path: path.name)
+        excess = len(revisions) - self.max_revisions
+        for old_revision in revisions[:excess]:
+            try:
+                old_revision.unlink()
+            except FileNotFoundError:
+                continue
+
+    def trim_by_age(
+        self: Self, resource_file_path: Path | str, retention_days: int | None = None
+    ) -> None:
+        """Remove snapshots older than retention_days.
+
+        Args:
+            resource_file_path: Relative path within the ``.fmu`` directory (e.g.,
+                ``logs/user_session_log.json``) whose cache entries should be trimmed.
+            retention_days: Maximum age in days to retain snapshots.
+                If None, uses CacheManager.RETENTION_DAYS (default: 30 days).
+        """
+        if retention_days is None:
+            retention_days = self.RETENTION_DAYS
+        revisions = self.list_revisions(resource_file_path)
+        cutoff = datetime.now(UTC) - timedelta(days=retention_days)
+
+        for revision in revisions:
+            try:
+                mtime_timestamp = revision.stat().st_mtime
+                file_time = datetime.fromtimestamp(mtime_timestamp, tz=UTC)
+            except (OSError, ValueError):
+                logger.warning("Skipping file with unreadable mtime: %s", revision.name)
+                continue
+
+            if file_time < cutoff:
+                revision.unlink()
+                logger.debug("Deleted old revision: %s", revision)