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

fmu/settings/_fmu_dir.py

@@ -4,12 +4,13 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any, Final, Self, TypeAlias, cast
 
 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
 
@@ -24,13 +25,22 @@ class FMUDirectoryBase:
     config: FMUConfigManager
     _lock: LockManager
     _cache_manager: CacheManager
-
-    def __init__(self: Self, base_path: str | Path) -> None:
+    _README_CONTENT: str = ""
+
+    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
@@ -39,8 +49,8 @@ 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)
+        self._lock = LockManager(self, timeout_seconds=lock_timeout_seconds)
+        self._cache_manager = CacheManager(self, max_revisions=cache_revisions)
 
         fmu_dir = self.base_path / ".fmu"
         if fmu_dir.exists():
@@ -72,8 +82,15 @@ class FMUDirectoryBase:
 
     @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
+        """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.
@@ -230,15 +247,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):
     if TYPE_CHECKING:
         config: ProjectConfigManager
 
-    def __init__(self, base_path: str | Path) -> None:
-        """Initializes a project-based .fmu directory."""
+    _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.
+
+        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.
@@ -286,11 +347,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
@@ -302,17 +369,38 @@ 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)
 
 
 class UserFMUDirectory(FMUDirectoryBase):
     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.
@@ -330,12 +418,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
@@ -346,14 +439,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
@@ -361,4 +459,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

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from datetime import UTC, datetime
 from pathlib import Path
-from typing import TYPE_CHECKING, Final, Self
+from typing import TYPE_CHECKING, ClassVar, Final, Self
 from uuid import uuid4
 
 from fmu.settings._logging import null_logger
@@ -25,6 +25,8 @@ _CACHEDIR_TAG_CONTENT: Final = (
 class CacheManager:
     """Stores complete file revisions under the `.fmu/cache` tree."""
 
+    MIN_REVISIONS: ClassVar[int] = 5
+
     def __init__(
         self: Self,
         fmu_dir: FMUDirectoryBase,
@@ -35,10 +37,11 @@ class CacheManager:
         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(0, max_revisions)
+        self._max_revisions = max(self.MIN_REVISIONS, max_revisions)
 
     @property
     def max_revisions(self: Self) -> int:
@@ -47,8 +50,13 @@ class CacheManager:
 
     @max_revisions.setter
     def max_revisions(self: Self, value: int) -> None:
-        """Update the per-resource revision retention."""
-        self._max_revisions = max(0, value)
+        """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,
@@ -65,12 +73,8 @@ class CacheManager:
             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).
+            Absolute filesystem path to the stored snapshot.
         """
-        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)

fmu/settings/_version.py

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

fmu/settings/models/project_config.py

@@ -23,6 +23,7 @@ class ProjectConfig(ResettableBaseModel):
     masterdata: Masterdata | None = Field(default=None)
     model: Model | None = Field(default=None)
     access: Access | None = Field(default=None)
+    cache_max_revisions: int = Field(default=5, ge=5)
 
     @classmethod
     def reset(cls: type[Self]) -> Self:
@@ -38,4 +39,5 @@ class ProjectConfig(ResettableBaseModel):
             masterdata=None,
             model=None,
             access=None,
+            cache_max_revisions=5,
         )

fmu/settings/models/user_config.py

@@ -10,6 +10,7 @@ import annotated_types
 from pydantic import (
     AwareDatetime,
     BaseModel,
+    Field,
     SecretStr,
     field_serializer,
     field_validator,
@@ -42,6 +43,7 @@ class UserConfig(ResettableBaseModel):
 
     version: VersionStr
     created_at: AwareDatetime
+    cache_max_revisions: int = Field(default=5, ge=5)
     user_api_keys: UserAPIKeys
     recent_project_directories: RecentProjectDirectories
 
@@ -51,6 +53,7 @@ class UserConfig(ResettableBaseModel):
         return cls(
             version=__version__,
             created_at=datetime.now(UTC),
+            cache_max_revisions=5,
             user_api_keys=UserAPIKeys(),
             recent_project_directories=[],
         )

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

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

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

@@ -1,14 +1,15 @@
 fmu/__init__.py,sha256=htx6HlMme77I6pZ8U256-2B2cMJuELsu3JN3YM2Efh4,144
 fmu/settings/__init__.py,sha256=CkEE7al_uBCQO1lxBKN5LzyCwzzH5Aq6kkEIR7f-zTw,336
-fmu/settings/_fmu_dir.py,sha256=J0K6CWlkk3Z5ojyOZaUDYQadx0_FiCyKNn1ZGs79h1o,11592
+fmu/settings/_fmu_dir.py,sha256=2mkrfvoqgdCd1soRPDJdZF6_51QYh3198igBYJRJzmo,15300
 fmu/settings/_global_config.py,sha256=C0_o99OhOc49ynz4h6ygbbHHH8OOI5lcVFr-9FCwD0c,9331
-fmu/settings/_init.py,sha256=ucueS0BlEsM3MkX7IaRISloH4vF7-_ZKSphrORbHgJ4,4381
+fmu/settings/_init.py,sha256=rgt5aZou54RiVAOegC4kzoigJcZefPY4Kv6ke7OAIxI,4014
 fmu/settings/_logging.py,sha256=nEdmZlNCBsB1GfDmFMKCjZmeuRp3CRlbz1EYUemc95Y,1104
-fmu/settings/_version.py,sha256=OrfVZdCDQ-QC6dUnxdROooJjwvLfeDMedTBstpAdSBU,704
+fmu/settings/_readme_texts.py,sha256=vVU_MTSZhN91z_Y16pCmA3fcCWxkWPF2aR1KfuI6Jwo,1067
+fmu/settings/_version.py,sha256=7vNQiXfKffK0nbqts6Xy6-E1b1YOm4EGigvgaHr83o4,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/cache_manager.py,sha256=LDCmPy06DdF7Uo_QJrCm9cCpT9cBMOIUEuvKR2YSDQQ,5787
 fmu/settings/_resources/config_managers.py,sha256=QcCLlSw8KdJKrkhGax5teFJzjgQG3ym7Ljs1DykjFbc,1570
 fmu/settings/_resources/lock_manager.py,sha256=3h1wRhDvn1xYkKoPs4I1e-6PO8Ctu8StdS7Nh5DW5O4,10508
 fmu/settings/_resources/pydantic_resource_manager.py,sha256=iCLO0xzTPhcYyhCoafKf7DAxjIDv8VBQIqRl-HYEDok,9472
@@ -16,10 +17,10 @@ fmu/settings/models/__init__.py,sha256=lRlXgl55ba2upmDzdvzx8N30JMq2Osnm8aa_xxTZn
 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.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,,
+fmu/settings/models/project_config.py,sha256=uja8F956m76ZrtAzuWogLySgb3seYmoTQp5xJayBqyE,1188
+fmu/settings/models/user_config.py,sha256=zl8-_UCvP9eygCuXksLo3eR9BmhPoeCRRn2Sn7ABsZY,2766
+fmu_settings-0.6.1.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+fmu_settings-0.6.1.dist-info/METADATA,sha256=BP6unasHIcniTkH6XDZKpBRbNPJCe6JoT-dKCETr1MI,2116
+fmu_settings-0.6.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+fmu_settings-0.6.1.dist-info/top_level.txt,sha256=Z-FIY3pxn0UK2Wxi9IJ7fKoLSraaxuNGi1eokiE0ShM,4
+fmu_settings-0.6.1.dist-info/RECORD,,