fmu-settings 0.2.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

fmu/settings/__init__.py

@@ -3,7 +3,7 @@
 try:
     from ._version import version
 
-    __version__ = version
+    __version__: str = version
 except ImportError:
     __version__ = version = "0.0.0"
 

fmu/settings/_fmu_dir.py

@@ -8,6 +8,7 @@ from ._resources.config_managers import (
     ProjectConfigManager,
     UserConfigManager,
 )
+from ._resources.lock_manager import LockManager
 from .models.project_config import ProjectConfig
 from .models.user_config import UserConfig
 
@@ -20,6 +21,7 @@ class FMUDirectoryBase:
     """Provides access to a .fmu directory and operations on its contents."""
 
     config: FMUConfigManager
+    _lock: LockManager
 
     def __init__(self: Self, base_path: str | Path) -> None:
         """Initializes access to a .fmu directory.
@@ -35,6 +37,7 @@ class FMUDirectoryBase:
         """
         self.base_path = Path(base_path).resolve()
         logger.debug(f"Initializing FMUDirectory from '{base_path}'")
+        self._lock = LockManager(self)
 
         fmu_dir = self.base_path / ".fmu"
         if fmu_dir.exists():

fmu/settings/_resources/config_managers.py

@@ -4,14 +4,13 @@ from __future__ import annotations
 
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Final, Self, TypeVar
-from uuid import UUID  # noqa TC003
 
 from pydantic import ValidationError
 
 from fmu.settings._logging import null_logger
 from fmu.settings.models.project_config import ProjectConfig
 from fmu.settings.models.user_config import UserConfig
-from fmu.settings.types import ResettableBaseModel, VersionStr  # noqa TC001
+from fmu.settings.types import ResettableBaseModel  # noqa: TC001
 
 from .pydantic_resource_manager import PydanticResourceManager
 

fmu/settings/_resources/lock_manager.py

@@ -0,0 +1,281 @@
+"""Manages a .lock file in a .fmu/ directory."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import socket
+import time
+import uuid
+from pathlib import Path
+from typing import TYPE_CHECKING, Final, Literal, Self
+
+from fmu.settings._logging import null_logger
+from fmu.settings.models.lock_info import LockInfo
+
+from .pydantic_resource_manager import PydanticResourceManager
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+    # Avoid circular dependency for type hint in __init__ only
+    from fmu.settings._fmu_dir import (
+        FMUDirectoryBase,
+    )
+
+logger: Final = null_logger(__name__)
+
+DEFAULT_LOCK_TIMEOUT: Final[int] = 1200  # 20 minutes
+
+
+class LockError(Exception):
+    """Raised when the lock cannot be acquired."""
+
+
+class LockManager(PydanticResourceManager[LockInfo]):
+    """Manages the .lock file."""
+
+    def __init__(
+        self: Self,
+        fmu_dir: FMUDirectoryBase,
+        timeout_seconds: int = DEFAULT_LOCK_TIMEOUT,
+    ) -> None:
+        """Initializes the lock manager.
+
+        Args:
+            fmu_dir: The FMUDirectory instance
+            timeout_seconds: Lock expiration time in seconds (default 20 minutes)
+        """
+        super().__init__(fmu_dir, LockInfo)
+        self._timeout_seconds = timeout_seconds
+        self._acquired_at: float | None = None
+
+    @property
+    def relative_path(self: Self) -> Path:
+        """Returns the relative path to the .lock file."""
+        return Path(".lock")
+
+    def acquire(self: Self, wait: bool = False, wait_timeout: float = 5.0) -> None:
+        """Acquire the lock.
+
+        Args:
+            wait: If true, wait for lock to become available
+            wait_timeout: Maximum time to wait in seconds
+
+        Raises:
+            LockError: If lock cannot be acquired
+        """
+        if self._acquired_at is not None:
+            raise LockError("Lock already acquired")
+
+        if wait and wait_timeout <= 0:
+            raise ValueError("wait_timeout must be positive")
+
+        start_time = time.time()
+
+        while True:
+            if self.exists and self._is_stale():
+                with contextlib.suppress(OSError):
+                    self.path.unlink()
+
+            if self._try_acquire():
+                return
+
+            if not wait:
+                lock_info = self._safe_load()
+                if lock_info:
+                    raise LockError(
+                        f"Lock file is held by {lock_info.user}@{lock_info.hostname} "
+                        f"(PID: {lock_info.pid}). "
+                        f"Expires at: {time.ctime(lock_info.expires_at)}."
+                    )
+                raise LockError(
+                    f"Invalid lock file exists at {self.path}. "
+                    "This file should be removed."
+                )
+
+            if time.time() - start_time > wait_timeout:
+                raise LockError(f"Timeout waiting for lock after {wait_timeout}s")
+
+            time.sleep(0.5)
+
+    def _try_acquire(self: Self) -> bool:
+        """Try to acquire lock. Returns True if successful.
+
+        This method creates the lock as a temporary file first to avoid race conditions.
+        Because we are operating on networked filesystems (NFS) the situation is a bit
+        more complex, but os.link() is an atomic operation, so try to link the temp file
+        after creating it.
+
+        Returns:
+            True if acquiring the lock succeeded
+        """
+        acquired_at = time.time()
+        lock_info = LockInfo(
+            pid=os.getpid(),
+            hostname=socket.gethostname(),
+            user=os.getenv("USER", "unknown"),
+            acquired_at=acquired_at,
+            expires_at=acquired_at + self._timeout_seconds,
+        )
+
+        temp_path = (
+            self.path.parent
+            / f".lock.{lock_info.hostname}.{lock_info.pid}.{uuid.uuid4().hex[:8]}"
+        )
+        lock_fd: int | None = None
+        try:
+            # O_WRONLY will allow only this process to write to the lock file.
+            lock_fd = os.open(temp_path, os.O_CREAT | os.O_WRONLY | os.O_EXCL)
+            try:
+                json_data = lock_info.model_dump_json(by_alias=True, indent=2)
+                os.write(lock_fd, json_data.encode())
+                os.fsync(lock_fd)
+            except Exception:
+                os.close(lock_fd)
+                raise
+
+            os.close(lock_fd)
+            lock_fd = None
+
+            try:
+                os.link(temp_path, self.path)
+                self._cache = lock_info
+                self._acquired_at = acquired_at
+                return True
+            except (OSError, FileExistsError):
+                return False
+        finally:  # Clean up temp file before we leave
+            if lock_fd is not None:
+                with contextlib.suppress(OSError):
+                    os.close(lock_fd)
+            with contextlib.suppress(OSError):
+                temp_path.unlink()
+
+    def is_locked(self: Self) -> 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)
+        if not lock_info:
+            return False
+        return time.time() < lock_info.expires_at
+
+    def is_acquired(self: Self) -> bool:
+        """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()
+
+    def refresh(self: Self) -> None:
+        """Refresh/extend the lock expiration time.
+
+        Raises:
+            LockError: If we don't hold the lock or it's invalid
+        """
+        if not self.exists:
+            raise LockError("Cannot refresh: lock file does not exist")
+
+        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."
+            )
+
+        lock_info.expires_at = time.time() + self._timeout_seconds
+        self.save(lock_info)
+
+    def release(self: Self) -> None:
+        """Release the lock."""
+        if self.exists:
+            lock_info = self._safe_load()
+            if lock_info and self._is_mine(lock_info):
+                with contextlib.suppress(ValueError):
+                    self.path.unlink()
+
+        self._acquired_at = None
+        self._cache = 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()
+        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."
+            )
+
+        temp_path = Path(f"{self.path}.tmp.{uuid.uuid4().hex[:8]}")
+        try:
+            with open(temp_path, "w", encoding="utf-8") as f:
+                f.write(data.model_dump_json(indent=2))
+                f.flush()
+                os.fsync(f.fileno())
+            temp_path.replace(self.path)
+            self._cache = data
+        except Exception as e:
+            with contextlib.suppress(OSError):
+                temp_path.unlink()
+            raise LockError(f"Failed to save lock: {e}") from e
+
+    def _is_mine(self: Self, lock_info: LockInfo) -> bool:
+        """Verifies if the calling process owns the lock."""
+        return (
+            lock_info.pid == os.getpid()
+            and lock_info.hostname == socket.gethostname()
+            and lock_info.acquired_at == self._acquired_at
+        )
+
+    def _safe_load(self: Self, force: 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)
+        except Exception:
+            return None
+
+    def _is_stale(self: Self) -> bool:
+        """Check if existing lock is stale (expired or process dead)."""
+        lock_info = self._safe_load()
+        if not lock_info:
+            return True
+
+        if time.time() > lock_info.expires_at:
+            return True
+
+        # If we aren't on the same host, we can't check the PID, so assume it's
+        # not stale.
+        if lock_info.hostname != socket.gethostname():
+            return False
+
+        try:
+            # Doesn't actually kill, just checks if it exists
+            os.kill(lock_info.pid, 0)
+            return False
+        except OSError:
+            return True
+
+    def __enter__(self: Self) -> Self:
+        """Context manager entry."""
+        self.acquire()
+        return self
+
+    def __exit__(
+        self: Self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> Literal[False]:
+        """Context manager exit."""
+        self.release()
+        return False
+
+    def __del__(self: Self) -> None:
+        """Clean-up if garbage collected."""
+        if self._acquired_at is not None:
+            self.release()

fmu/settings/_resources/pydantic_resource_manager.py

@@ -58,8 +58,8 @@ class PydanticResourceManager(Generic[T]):
             Validated Pydantic model
 
         Raises:
-            FileNotFoundError: If the resource file doesn't exist
-            ValidationError: If the data doesn't match the model schema
+            ValueError: If the resource file is missing or data does not match the
+            model schema
         """
         if self._cache is None or force:
             if not self.exists:

fmu/settings/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.2.0'
-__version_tuple__ = version_tuple = (0, 2, 0)
+__version__ = version = '0.3.1'
+__version_tuple__ = version_tuple = (0, 3, 1)
 
 __commit_id__ = commit_id = None

fmu/settings/models/lock_info.py

@@ -0,0 +1,30 @@
+"""Models related to locking a .fmu directory against writes."""
+
+from pydantic import BaseModel, Field
+
+from fmu.settings import __version__
+from fmu.settings.types import VersionStr
+
+
+class LockInfo(BaseModel):
+    """Represents a .fmu directory lock file."""
+
+    pid: int
+    """Process ID of the lock holder."""
+
+    hostname: str
+    """Hostname where the lock was acquired."""
+
+    user: str
+    """User who acquired the lock."""
+
+    acquired_at: float
+    """Unix timestamp when lock was acquired."""
+
+    expires_at: float
+    """Unix timestamp when lock expires."""
+
+    version: VersionStr = Field(default=__version__)
+    """The fmu-settings version acquiring the lock.
+
+    Used for debugging."""

fmu/settings/models/project_config.py

@@ -8,7 +8,7 @@ from pydantic import AwareDatetime, Field
 
 from fmu.datamodels.fmu_results.fields import Access, Masterdata, Model
 from fmu.settings import __version__
-from fmu.settings.types import ResettableBaseModel, VersionStr  # noqa TC001
+from fmu.settings.types import ResettableBaseModel, VersionStr  # noqa: TC001
 
 
 class ProjectConfig(ResettableBaseModel):

fmu/settings/models/user_config.py

@@ -5,7 +5,6 @@ from __future__ import annotations
 from datetime import UTC, datetime
 from pathlib import Path
 from typing import Annotated, Self
-from uuid import UUID  # noqa TC003
 
 import annotated_types
 from pydantic import (
@@ -17,7 +16,7 @@ from pydantic import (
 )
 
 from fmu.settings import __version__
-from fmu.settings.types import ResettableBaseModel, VersionStr  # noqa TC001
+from fmu.settings.types import ResettableBaseModel, VersionStr  # noqa: TC001
 
 RecentProjectDirectories = Annotated[list[Path], annotated_types.Len(0, 5)]
 

{fmu_settings-0.2.0.dist-info → fmu_settings-0.3.1.dist-info}/METADATA

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

fmu_settings-0.3.1.dist-info/RECORD

@@ -0,0 +1,23 @@
+fmu/__init__.py,sha256=htx6HlMme77I6pZ8U256-2B2cMJuELsu3JN3YM2Efh4,144
+fmu/settings/__init__.py,sha256=CkEE7al_uBCQO1lxBKN5LzyCwzzH5Aq6kkEIR7f-zTw,336
+fmu/settings/_fmu_dir.py,sha256=Br_hcfAXshiuDyWqG_qx5VXFpsCBJO1XDMPzdxxesoE,10684
+fmu/settings/_init.py,sha256=5CT7tV2XHz5wuLh97XozyLiKpwogrsfjpxm2dpn7KWE,4097
+fmu/settings/_logging.py,sha256=nEdmZlNCBsB1GfDmFMKCjZmeuRp3CRlbz1EYUemc95Y,1104
+fmu/settings/_version.py,sha256=gGLpQUQx-ty9SEy9PYw9OgJWWzJLBnCpfJOfzL7SjlI,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/config_managers.py,sha256=IjOtS2lSU55GE_TWqHjbBPAzE8xQyVBvpHcfm0hTSnI,6822
+fmu/settings/_resources/lock_manager.py,sha256=_xzSJNF_qcpKpo8AxMfEgOhPxKXl3fZ2lRi0_y2eUEg,9206
+fmu/settings/_resources/pydantic_resource_manager.py,sha256=9zFcOUJKeapxbYvgerf3t2_9pL5acFU2rknri67pXt0,3131
+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.3.1.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+fmu_settings-0.3.1.dist-info/METADATA,sha256=4reIMuluyZnwiu3CuLCdYXCAJz7hPu4i-_R3IbJwi08,2024
+fmu_settings-0.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+fmu_settings-0.3.1.dist-info/top_level.txt,sha256=Z-FIY3pxn0UK2Wxi9IJ7fKoLSraaxuNGi1eokiE0ShM,4
+fmu_settings-0.3.1.dist-info/RECORD,,

fmu_settings-0.2.0.dist-info/RECORD

@@ -1,21 +0,0 @@
-fmu/__init__.py,sha256=htx6HlMme77I6pZ8U256-2B2cMJuELsu3JN3YM2Efh4,144
-fmu/settings/__init__.py,sha256=x96dVVR-2n2lYD84LGbL7W8l3-r7W_0reUTKZlE7S34,331
-fmu/settings/_fmu_dir.py,sha256=E8ULohZKwMixkuw9cXK20IxaHaRXmWQ1vbE02QAX_YU,10573
-fmu/settings/_init.py,sha256=5CT7tV2XHz5wuLh97XozyLiKpwogrsfjpxm2dpn7KWE,4097
-fmu/settings/_logging.py,sha256=nEdmZlNCBsB1GfDmFMKCjZmeuRp3CRlbz1EYUemc95Y,1104
-fmu/settings/_version.py,sha256=Dg8AmJomLVpjKL6prJylOONZAPRtB86LOce7dorQS_A,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/config_managers.py,sha256=b8DUtRHti1n2pSuw5eCQko7e7NKOzP2BH6dNPJFd2ck,6869
-fmu/settings/_resources/pydantic_resource_manager.py,sha256=t4Rp6MOSIq85iKfDHZLJxeGRj8S3SKanWHWri0p9wV8,3161
-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/project_config.py,sha256=K7y4PZMuq5wD-0Br60xfffBN6QQUV8viKGjjOcCB-7M,1098
-fmu/settings/models/user_config.py,sha256=UrRcbxJAGn1e7IeE0_v1oPWVOk-DGekRG49pXzDr83o,2701
-fmu_settings-0.2.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-fmu_settings-0.2.0.dist-info/METADATA,sha256=Kjzn1O0vvAAYoYAoC-Jo8IzN0H-V7HWwwV3Io47N41w,2024
-fmu_settings-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-fmu_settings-0.2.0.dist-info/top_level.txt,sha256=Z-FIY3pxn0UK2Wxi9IJ7fKoLSraaxuNGi1eokiE0ShM,4
-fmu_settings-0.2.0.dist-info/RECORD,,