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

fmu/settings/_fmu_dir.py

@@ -1,9 +1,10 @@
 """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 ._logging import null_logger
+from ._resources.cache_manager import CacheManager
 from ._resources.config_managers import (
     ProjectConfigManager,
     UserConfigManager,
@@ -22,6 +23,7 @@ class FMUDirectoryBase:
 
     config: FMUConfigManager
     _lock: LockManager
+    _cache_manager: CacheManager
 
     def __init__(self: Self, base_path: str | Path) -> None:
         """Initializes access to a .fmu directory.
@@ -38,6 +40,7 @@ class FMUDirectoryBase:
         self.base_path = Path(base_path).resolve()
         logger.debug(f"Initializing FMUDirectory from '{base_path}'")
         self._lock = LockManager(self)
+        self._cache_manager = CacheManager(self, max_revisions=5)
 
         fmu_dir = self.base_path / ".fmu"
         if fmu_dir.exists():
@@ -57,6 +60,21 @@ 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."""
+        self._cache_manager.max_revisions = value
+
     def get_config_value(self: Self, key: str, default: Any = None) -> Any:
         """Gets a configuration value by key.
 
@@ -214,7 +232,8 @@ class FMUDirectoryBase:
 
 
 class ProjectFMUDirectory(FMUDirectoryBase):
-    config: ProjectConfigManager
+    if TYPE_CHECKING:
+        config: ProjectConfigManager
 
     def __init__(self, base_path: str | Path) -> None:
         """Initializes a project-based .fmu directory."""
@@ -287,7 +306,8 @@ class ProjectFMUDirectory(FMUDirectoryBase):
 
 
 class UserFMUDirectory(FMUDirectoryBase):
-    config: UserConfigManager
+    if TYPE_CHECKING:
+        config: UserConfigManager
 
     def __init__(self) -> None:
         """Initializes a project-based .fmu directory."""

fmu/settings/_resources/cache_manager.py

@@ -0,0 +1,149 @@
+"""Utilities for storing revision snapshots of .fmu files."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, 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."""
+
+    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.
+        """
+        self._fmu_dir = fmu_dir
+        self._cache_root = Path("cache")
+        self._max_revisions = max(0, 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."""
+        self._max_revisions = max(0, value)
+
+    def store_revision(
+        self: Self,
+        resource_file_path: Path | str,
+        content: str,
+        encoding: str = "utf-8",
+    ) -> 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.
+
+        Returns:
+            Absolute filesystem path to the stored snapshot, or ``None`` if caching is
+            disabled (``max_revisions`` equals zero).
+        """
+        if self.max_revisions == 0:
+            return None
+
+        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)
+
+        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

fmu/settings/_resources/lock_manager.py

@@ -32,9 +32,15 @@ class LockError(Exception):
     """Raised when the lock cannot be acquired."""
 
 
+class LockNotFoundError(FileNotFoundError):
+    """Raised when the lock cannot be found."""
+
+
 class LockManager(PydanticResourceManager[LockInfo]):
     """Manages the .lock file."""
 
+    cache_enabled: bool = False
+
     def __init__(
         self: Self,
         fmu_dir: FMUDirectoryBase,
@@ -82,7 +88,7 @@ class LockManager(PydanticResourceManager[LockInfo]):
                 return
 
             if not wait:
-                lock_info = self._safe_load()
+                lock_info = self.safe_load()
                 if lock_info:
                     raise LockError(
                         f"Lock file is held by {lock_info.user}@{lock_info.hostname} "
@@ -152,12 +158,16 @@ class LockManager(PydanticResourceManager[LockInfo]):
             with contextlib.suppress(OSError):
                 temp_path.unlink()
 
-    def is_locked(self: Self) -> bool:
+    def is_locked(self: Self, *, propagate_errors: bool = False) -> bool:
         """Returns whether or not the lock is locked by anyone.
 
         This does a force load on the lock file.
         """
-        lock_info = self._safe_load(force=True)
+        lock_info = (
+            self.load(force=True, store_cache=False)
+            if propagate_errors
+            else self.safe_load(force=True, store_cache=False)
+        )
         if not lock_info:
             return False
         return time.time() < lock_info.expires_at
@@ -166,15 +176,16 @@ class LockManager(PydanticResourceManager[LockInfo]):
         """Returns whether or not the lock is currently acquired by this instance."""
         if self._cache is None or self._acquired_at is None:
             return False
-        return self._is_mine(self._cache) and not self._is_stale()
+
+        current_lock = self.safe_load(force=True, store_cache=False)
+        if current_lock is None:
+            return False
+
+        return self._is_mine(current_lock) and not self._is_stale()
 
     def ensure_can_write(self: Self) -> None:
         """Raise PermissionError if another process currently holds the lock."""
-        try:
-            lock_info = self.load(force=True, store_cache=False)
-        except Exception:
-            lock_info = None
-
+        lock_info = self.safe_load(force=True, store_cache=False)
         if (
             self.exists
             and lock_info is not None
@@ -196,9 +207,9 @@ class LockManager(PydanticResourceManager[LockInfo]):
         if not self.exists:
             if self.is_acquired():
                 self.release()
-            raise LockError("Cannot refresh: lock file does not exist")
+            raise LockNotFoundError("Cannot refresh: lock file does not exist")
 
-        lock_info = self._safe_load()
+        lock_info = self.safe_load()
         if not lock_info or not self._is_mine(lock_info):
             raise LockError(
                 "Cannot refresh: lock file is held by another process or host."
@@ -210,7 +221,7 @@ class LockManager(PydanticResourceManager[LockInfo]):
     def release(self: Self) -> None:
         """Release the lock."""
         if self.exists:
-            lock_info = self._safe_load()
+            lock_info = self.safe_load()
             if lock_info and self._is_mine(lock_info):
                 with contextlib.suppress(ValueError):
                     self.path.unlink()
@@ -218,12 +229,15 @@ class LockManager(PydanticResourceManager[LockInfo]):
         self._acquired_at = None
         self._cache = None
 
-    def save(self: Self, data: LockInfo) -> None:
+    def save(
+        self: Self,
+        data: LockInfo,
+    ) -> None:
         """Save the lockfile in an NFS-atomic manner.
 
         This overrides save() from the Pydantic resource manager.
         """
-        lock_info = self._safe_load()
+        lock_info = self.safe_load()
         if not lock_info or not self._is_mine(lock_info):
             raise LockError(
                 "Failed to save lock: lock file is held by another process or host."
@@ -250,20 +264,22 @@ class LockManager(PydanticResourceManager[LockInfo]):
             and lock_info.acquired_at == self._acquired_at
         )
 
-    def _safe_load(self: Self, force: bool = False) -> LockInfo | None:
+    def safe_load(
+        self: Self, force: bool = False, store_cache: bool = False
+    ) -> LockInfo | None:
         """Load lock info, returning None if corrupted.
 
         Because this file does not exist in a static state, wrap around loading it.
         """
         try:
-            return self.load(force=force)
+            return self.load(force=force, store_cache=store_cache)
         except Exception:
             return None
 
     def _is_stale(self: Self, lock_info: LockInfo | None = None) -> bool:
         """Check if existing lock is stale (expired or process dead)."""
         if lock_info is None:
-            lock_info = self._safe_load()
+            lock_info = self.safe_load()
 
         if not lock_info:
             return True

fmu/settings/_resources/pydantic_resource_manager.py

@@ -22,6 +22,8 @@ MutablePydanticResource = TypeVar("MutablePydanticResource", bound=ResettableBas
 class PydanticResourceManager(Generic[PydanticResource]):
     """Base class for managing resources represented by Pydantic models."""
 
+    cache_enabled: bool = True
+
     def __init__(
         self: Self, fmu_dir: FMUDirectoryBase, model_class: type[PydanticResource]
     ) -> None:
@@ -99,15 +101,22 @@ class PydanticResourceManager(Generic[PydanticResource]):
 
         return self._cache
 
-    def save(self: Self, model: PydanticResource) -> None:
+    def save(
+        self: Self,
+        model: PydanticResource,
+    ) -> None:
         """Save the Pydantic model to disk.
 
         Args:
-            model: Validated Pydantic model instance
+            model: Validated Pydantic model instance.
         """
         self.fmu_dir._lock.ensure_can_write()
         json_data = model.model_dump_json(by_alias=True, indent=2)
         self.fmu_dir.write_text_file(self.relative_path, json_data)
+
+        if self.cache_enabled and self.exists:
+            self.fmu_dir.cache.store_revision(self.relative_path, json_data)
+
         self._cache = model
 
 

fmu/settings/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.5.2'
-__version_tuple__ = version_tuple = (0, 5, 2)
+__version__ = version = '0.5.4'
+__version_tuple__ = version_tuple = (0, 5, 4)
 
 __commit_id__ = commit_id = None

{fmu_settings-0.5.2.dist-info → fmu_settings-0.5.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fmu-settings
-Version: 0.5.2
+Version: 0.5.4
 Summary: A library for managing FMU settings
 Author-email: Equinor <fg-fmu_atlas@equinor.com>
 License: GPL-3.0

{fmu_settings-0.5.2.dist-info → fmu_settings-0.5.4.dist-info}/RECORD

@@ -1,24 +1,25 @@
 fmu/__init__.py,sha256=htx6HlMme77I6pZ8U256-2B2cMJuELsu3JN3YM2Efh4,144
 fmu/settings/__init__.py,sha256=CkEE7al_uBCQO1lxBKN5LzyCwzzH5Aq6kkEIR7f-zTw,336
-fmu/settings/_fmu_dir.py,sha256=XeZjec78q0IUOpBq-VMkKoWtzXwBeQi2qWRIh_SIFwU,10859
+fmu/settings/_fmu_dir.py,sha256=J0K6CWlkk3Z5ojyOZaUDYQadx0_FiCyKNn1ZGs79h1o,11592
 fmu/settings/_global_config.py,sha256=C0_o99OhOc49ynz4h6ygbbHHH8OOI5lcVFr-9FCwD0c,9331
 fmu/settings/_init.py,sha256=ucueS0BlEsM3MkX7IaRISloH4vF7-_ZKSphrORbHgJ4,4381
 fmu/settings/_logging.py,sha256=nEdmZlNCBsB1GfDmFMKCjZmeuRp3CRlbz1EYUemc95Y,1104
-fmu/settings/_version.py,sha256=LGYtjQ6cyPZC_N0AovMIeSYYDK21050nm3HYgDanQBM,704
+fmu/settings/_version.py,sha256=OrfVZdCDQ-QC6dUnxdROooJjwvLfeDMedTBstpAdSBU,704
 fmu/settings/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 fmu/settings/types.py,sha256=aeXEsznBTT1YRRY_LSRqK1j2gmMmyLYYTGYl3a9fweU,513
 fmu/settings/_resources/__init__.py,sha256=LHYR_F7lNGdv8N6R3cEwds5CJQpkOthXFqsEs24vgF8,118
+fmu/settings/_resources/cache_manager.py,sha256=TCVefkQEZuEdrzS0yOs7K-fCMouU4fctRtEvj4Du28M,5656
 fmu/settings/_resources/config_managers.py,sha256=QcCLlSw8KdJKrkhGax5teFJzjgQG3ym7Ljs1DykjFbc,1570
-fmu/settings/_resources/lock_manager.py,sha256=ekGE5mTcjEWRyoBSIeqaX1r53-WStpYeJYepkOPYi3Q,10061
-fmu/settings/_resources/pydantic_resource_manager.py,sha256=BUWO6IHSoT0Ma6QgseweEf7uiGeMwHBEoCyGYPYYFdA,9290
+fmu/settings/_resources/lock_manager.py,sha256=3h1wRhDvn1xYkKoPs4I1e-6PO8Ctu8StdS7Nh5DW5O4,10508
+fmu/settings/_resources/pydantic_resource_manager.py,sha256=iCLO0xzTPhcYyhCoafKf7DAxjIDv8VBQIqRl-HYEDok,9472
 fmu/settings/models/__init__.py,sha256=lRlXgl55ba2upmDzdvzx8N30JMq2Osnm8aa_xxTZn8A,112
 fmu/settings/models/_enums.py,sha256=SQUZ-2mQcTx4F0oefPFfuQzMKsKTSFSB-wq_CH7TBRE,734
 fmu/settings/models/_mappings.py,sha256=Z4Ex7MtmajBr6FjaNzmwDRwtJlaZZ8YKh9NDmZHRKPI,2832
 fmu/settings/models/lock_info.py,sha256=-oHDF9v9bDLCoFvEg4S6XXYLeo19zRAZ8HynCv75VWg,711
 fmu/settings/models/project_config.py,sha256=pxb54JmpXNMVAFUu_yJ89dNrYEk6hrPuFfFUpf84Jh0,1099
 fmu/settings/models/user_config.py,sha256=dWFTcZY6UnEgNTuGqB-izraJ657PecsW0e0Nt9GBDhI,2666
-fmu_settings-0.5.2.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-fmu_settings-0.5.2.dist-info/METADATA,sha256=dxi2pe4SgYJwTY6beiEPoLx7lEqjzZWq9UcpX3gir_s,2116
-fmu_settings-0.5.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-fmu_settings-0.5.2.dist-info/top_level.txt,sha256=Z-FIY3pxn0UK2Wxi9IJ7fKoLSraaxuNGi1eokiE0ShM,4
-fmu_settings-0.5.2.dist-info/RECORD,,
+fmu_settings-0.5.4.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+fmu_settings-0.5.4.dist-info/METADATA,sha256=kysnXaWPfT7_e-lqxRIEOgbdirMo-VvzbcdNeFztyzA,2116
+fmu_settings-0.5.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+fmu_settings-0.5.4.dist-info/top_level.txt,sha256=Z-FIY3pxn0UK2Wxi9IJ7fKoLSraaxuNGi1eokiE0ShM,4
+fmu_settings-0.5.4.dist-info/RECORD,,