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

fmu/settings/_resources/changelog_manager.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import os
+import socket
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Self
+
+from pydantic import BaseModel
+
+from fmu.settings._resources.log_manager import LogManager
+from fmu.settings.models._enums import ChangeType, FilterType
+from fmu.settings.models.change_info import ChangeInfo
+from fmu.settings.models.log import Filter, Log, LogFileName
+
+if TYPE_CHECKING:
+    # Avoid circular dependency for type hint in __init__ only
+    from fmu.settings._fmu_dir import (
+        FMUDirectoryBase,
+    )
+
+
+class ChangelogManager(LogManager[ChangeInfo]):
+    """Manages the .fmu changelog file."""
+
+    def __init__(self: Self, fmu_dir: FMUDirectoryBase) -> None:
+        """Initializes the Change log resource manager."""
+        super().__init__(fmu_dir, Log[ChangeInfo])
+
+    @property
+    def relative_path(self: Self) -> Path:
+        """Returns the relative path to the log file."""
+        return Path("logs") / LogFileName.changelog
+
+    def log_update_to_changelog(
+        self: Self,
+        updates: dict[str, Any],
+        old_resource_dict: dict[str, Any],
+        relative_path: Path,
+    ) -> None:
+        """Logs the update of a resource to the changelog."""
+        _MISSING_KEY = object()
+        for key, new_value in updates.items():
+            change_type = ChangeType.update
+            if "." in key:
+                old_value = self._get_dot_notation_key(
+                    resource_dict=old_resource_dict, key=key, default=_MISSING_KEY
+                )
+            else:
+                old_value = old_resource_dict.get(key, _MISSING_KEY)
+
+            if old_value != _MISSING_KEY:
+                old_value_string = (
+                    str(old_value.model_dump())
+                    if isinstance(old_value, BaseModel)
+                    else str(old_value)
+                )
+                new_value_string = (
+                    str(new_value.model_dump())
+                    if isinstance(new_value, BaseModel)
+                    else str(new_value)
+                )
+                change_string = (
+                    f"Updated field '{key}'. Old value: {old_value_string}"
+                    f" -> New value: {new_value_string}"
+                )
+            else:
+                change_type = ChangeType.add
+                new_value_string = (
+                    str(new_value.model_dump())
+                    if isinstance(new_value, BaseModel)
+                    else str(new_value)
+                )
+                change_string = f"Added field '{key}'. New value: {new_value_string}"
+
+            change_entry = ChangeInfo(
+                timestamp=datetime.now(UTC),
+                change_type=change_type,
+                user=os.getenv("USER", "unknown"),
+                path=self.fmu_dir.path,
+                change=change_string,
+                hostname=socket.gethostname(),
+                file=str(relative_path),
+                key=key,
+            )
+            self.add_log_entry(change_entry)
+
+    def log_merge_to_changelog(
+        self: Self, source_path: Path, incoming_path: Path, merged_resources: list[str]
+    ) -> None:
+        """Logs a change entry with merge details to the changelog."""
+        resources_string = ", ".join([f"'{resource}'" for resource in merged_resources])
+        change_string = (
+            f"Merged resources {resources_string} from "
+            f"'{incoming_path}' into '{source_path}'."
+        )
+        self.add_log_entry(
+            ChangeInfo(
+                timestamp=datetime.now(UTC),
+                change_type=ChangeType.merge,
+                user=os.getenv("USER", "unknown"),
+                path=source_path,
+                change=change_string,
+                hostname=socket.gethostname(),
+                file=resources_string,
+                key=".fmu",
+            )
+        )
+
+    def _get_latest_change_timestamp(self: Self) -> datetime:
+        """Get the timestamp of the latest change entry in the changelog."""
+        return self.load()[-1].timestamp
+
+    def get_changelog_diff(
+        self: Self, incoming_changelog: ChangelogManager
+    ) -> Log[ChangeInfo]:
+        """Get new entries from the incoming changelog.
+
+        All log entries from the incoming changelog newer than the
+        log entries in the current changelog are returned.
+        """
+        if self.exists and incoming_changelog.exists:
+            starting_point = self._get_latest_change_timestamp()
+            return incoming_changelog.filter_log(
+                Filter(
+                    field_name="timestamp",
+                    filter_value=str(starting_point),
+                    filter_type=FilterType.date,
+                    operator=">",
+                )
+            )
+        raise FileNotFoundError(
+            "Changelog resources to diff must exist in both directories: "
+            f"Current changelog resource exists: {self.exists}. "
+            f"Incoming changelog resource exists: {incoming_changelog.exists}."
+        )
+
+    def merge_changelog(
+        self: Self, incoming_changelog: ChangelogManager
+    ) -> Log[ChangeInfo]:
+        """Add new entries from the incoming changelog to the current changelog.
+
+        All log entries from the incoming changelog newer than the
+        log entries in the current changelog are added.
+        """
+        new_log_entries = self.get_changelog_diff(incoming_changelog)
+        self.merge_changes(new_log_entries.root)
+        return self.load()
+
+    def merge_changes(self: Self, change: list[ChangeInfo]) -> Log[ChangeInfo]:
+        """Merge a list of changes into the current changelog.
+
+        All log entries in the change object are added to the changelog.
+        """
+        for entry in change:
+            self.add_log_entry(entry)
+        return self.load()

fmu/settings/_resources/config_managers.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import getpass
+from datetime import UTC, datetime
 from pathlib import Path
 from typing import TYPE_CHECKING, Final, Self
 
@@ -35,6 +37,14 @@ class ProjectConfigManager(MutablePydanticResourceManager[ProjectConfig]):
         """Returns the relative path to the config file."""
         return Path("config.json")
 
+    def save(self: Self, model: ProjectConfig) -> None:
+        """Save the ProjectConfig to disk, updating last_modified fields."""
+        model_dict = model.model_dump()
+        model_dict["last_modified_at"] = datetime.now(UTC)
+        model_dict["last_modified_by"] = getpass.getuser()
+        updated_model = ProjectConfig.model_validate(model_dict)
+        super().save(updated_model)
+
 
 class UserConfigManager(MutablePydanticResourceManager[UserConfig]):
     """Manages the .fmu configuration file in a user's home directory."""
@@ -47,3 +57,10 @@ class UserConfigManager(MutablePydanticResourceManager[UserConfig]):
     def relative_path(self: Self) -> Path:
         """Returns the relative path to the config file."""
         return Path("config.json")
+
+    def save(self: Self, model: UserConfig) -> None:
+        """Save the UserConfig to disk, updating last_modified_at."""
+        model_dict = model.model_dump()
+        model_dict["last_modified_at"] = datetime.now(UTC)
+        updated_model = UserConfig.model_validate(model_dict)
+        super().save(updated_model)

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."""
 
+    automatic_caching: 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/log_manager.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Generic, Self
+
+import pandas as pd
+from pydantic import ValidationError
+
+from fmu.settings._resources.pydantic_resource_manager import PydanticResourceManager
+from fmu.settings.models._enums import FilterType
+from fmu.settings.models.log import Filter, Log, LogEntryType
+
+if TYPE_CHECKING:
+    # Avoid circular dependency for type hint in __init__ only
+    from fmu.settings._fmu_dir import (
+        FMUDirectoryBase,
+    )
+
+
+class LogManager(PydanticResourceManager[Log[LogEntryType]], Generic[LogEntryType]):
+    """Manages the .fmu log files."""
+
+    automatic_caching: bool = False
+
+    def __init__(
+        self: Self, fmu_dir: FMUDirectoryBase, model_class: type[Log[LogEntryType]]
+    ) -> None:
+        """Initializes the log resource manager."""
+        self._cached_dataframe: pd.DataFrame | None = None
+        super().__init__(fmu_dir, model_class)
+
+    def add_log_entry(self: Self, log_entry: LogEntryType) -> None:
+        """Adds a log entry to the log resource."""
+        try:
+            validated_entry = log_entry.model_validate(log_entry.model_dump())
+            log_model: Log[LogEntryType] = (
+                self.load() if self.exists else self.model_class([])
+            )
+            log_model.add_entry(validated_entry)
+            self.save(log_model)
+            self._cached_dataframe = None
+        except ValidationError as e:
+            raise ValueError(
+                f"Invalid log entry added to '{self.model_class.__name__}' with "
+                f"value '{log_entry}': '{e}"
+            ) from e
+
+    def filter_log(self: Self, filter: Filter) -> Log[LogEntryType]:
+        """Filters the log resource with the provided filter."""
+        if self._cached_dataframe is None:
+            log_model: Log[LogEntryType] = self.load()
+            df_log = pd.DataFrame([entry.model_dump() for entry in log_model])
+            self._cached_dataframe = df_log
+        df_log = self._cached_dataframe
+
+        if filter.filter_type == FilterType.text and filter.operator not in {
+            "==",
+            "!=",
+        }:
+            raise ValueError(
+                f"Invalid filter operator {filter.operator} applied to "
+                f"'{FilterType.text}' field {filter.field_name} when filtering "
+                f"log resource {self.model_class.__name__} "
+                f"with value {filter.filter_value}."
+            )
+
+        match filter.operator:
+            case "==":
+                filtered_df = df_log[
+                    df_log[filter.field_name] == filter.parse_filter_value()
+                ]
+            case "!=":
+                filtered_df = df_log[
+                    df_log[filter.field_name] != filter.parse_filter_value()
+                ]
+            case "<=":
+                filtered_df = df_log[
+                    df_log[filter.field_name] <= filter.parse_filter_value()
+                ]
+            case "<":
+                filtered_df = df_log[
+                    df_log[filter.field_name] < filter.parse_filter_value()
+                ]
+            case ">=":
+                filtered_df = df_log[
+                    df_log[filter.field_name] >= filter.parse_filter_value()
+                ]
+            case ">":
+                filtered_df = df_log[
+                    df_log[filter.field_name] > filter.parse_filter_value()
+                ]
+            case _:
+                raise ValueError(
+                    "Invalid filter operator applied when "
+                    f"filtering log resource {self.model_class.__name__} "
+                )
+
+        filtered_dict = filtered_df.to_dict("records")
+        return self.model_class.model_validate(filtered_dict)