fmu-settings 0.0.1__py3-none-any.whl

fmu/settings/models/project_config.py

@@ -0,0 +1,49 @@
+"""The model for config.json."""
+
+import getpass
+from datetime import UTC, datetime
+from typing import Self
+from uuid import UUID  # noqa TC003
+
+from pydantic import AwareDatetime, BaseModel, Field
+
+from fmu.settings import __version__
+from fmu.settings.types import ResettableBaseModel, VersionStr  # noqa TC001
+
+from .smda import Smda
+
+
+class Masterdata(BaseModel):
+    """The ``masterdata`` block contains information related to masterdata.
+
+    Currently, SMDA holds the masterdata.
+    """
+
+    smda: Smda | None = Field(default=None)
+    """Block containing SMDA-related attributes. See :class:`Smda`."""
+
+
+class ProjectConfig(ResettableBaseModel):
+    """The configuration file in a .fmu directory.
+
+    Stored as config.json.
+    """
+
+    version: VersionStr
+    created_at: AwareDatetime
+    created_by: str
+    masterdata: Masterdata
+
+    @classmethod
+    def reset(cls: type[Self]) -> Self:
+        """Resets the configuration to defaults.
+
+        Returns:
+            The new default Config object
+        """
+        return cls(
+            version=__version__,
+            created_at=datetime.now(UTC),
+            created_by=getpass.getuser(),
+            masterdata=Masterdata(),
+        )

fmu/settings/models/smda.py

@@ -0,0 +1,90 @@
+"""Models for SMDA masterdata."""
+
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+from fmu.settings.types import VersionStr  # noqa TC001
+
+
+class SmdaIdentifier(BaseModel):
+    """The identifier for something known to SMDA."""
+
+    identifier: str
+    """Identifier known to SMDA."""
+
+    uuid: UUID
+    """Identifier known to SMDA."""
+
+
+class CountryItem(SmdaIdentifier):
+    """A single country in the list of countries known to SMDA."""
+
+    identifier: str = Field(examples=["Norway"])
+    """Identifier known to SMDA."""
+
+    uuid: UUID = Field(examples=["15ce3b84-766f-4c93-9050-b154861f9100"])
+    """Identifier known to SMDA."""
+
+
+class FieldItem(SmdaIdentifier):
+    """A single field in the list of fields known to SMDA."""
+
+    identifier: str = Field(examples=["OseFax"])
+    """Identifier known to SMDA."""
+
+    uuid: UUID = Field(examples=["15ce3b84-766f-4c93-9050-b154861f9100"])
+    """Identifier known to SMDA."""
+
+
+class CoordinateSystem(SmdaIdentifier):
+    """Contains the coordinate system known to SMDA."""
+
+    identifier: str = Field(examples=["ST_WGS84_UTM37N_P32637"])
+    """Identifier known to SMDA."""
+
+    uuid: UUID = Field(examples=["15ce3b84-766f-4c93-9050-b154861f9100"])
+    """Identifier known to SMDA."""
+
+
+class StratigraphicColumn(SmdaIdentifier):
+    """Contains the stratigraphic column known to SMDA."""
+
+    identifier: str = Field(examples=["DROGON_2020"])
+    """Identifier known to SMDA."""
+
+    uuid: UUID = Field(examples=["15ce3b84-766f-4c93-9050-b154861f9100"])
+    """Identifier known to SMDA."""
+
+
+class DiscoveryItem(BaseModel):
+    """A single discovery in the list of discoveries known to SMDA."""
+
+    short_identifier: str = Field(examples=["SomeDiscovery"])
+    """Identifier known to SMDA."""
+
+    uuid: UUID = Field(examples=["15ce3b84-766f-4c93-9050-b154861f9100"])
+    """Identifier known to SMDA."""
+
+
+class Smda(BaseModel):
+    """Contains SMDA-related attributes."""
+
+    coordinate_system: CoordinateSystem
+    """Reference to coordinate system known to SMDA.  See :class:`CoordinateSystem`."""
+
+    country: list[CountryItem]
+    """A list referring to countries known to SMDA. First item is primary.
+    See :class:`CountryItem`."""
+
+    discovery: list[DiscoveryItem]
+    """A list referring to discoveries known to SMDA. First item is primary.
+    See :class:`DiscoveryItem`."""
+
+    field: list[FieldItem]
+    """A list referring to fields known to SMDA. First item is primary.
+    See :class:`FieldItem`."""
+
+    stratigraphic_column: StratigraphicColumn
+    """Reference to stratigraphic column known to SMDA.
+    See :class:`StratigraphicColumn`."""

fmu/settings/models/user_config.py

@@ -0,0 +1,73 @@
+"""The model for config.json."""
+
+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 AwareDatetime, BaseModel, SecretStr, field_serializer
+
+from fmu.settings import __version__
+from fmu.settings.types import ResettableBaseModel, VersionStr  # noqa TC001
+
+RecentDirectories = Annotated[set[Path], annotated_types.Len(0, 5)]
+
+
+class UserAPIKeys(BaseModel):
+    """Known API keys stored in a user config."""
+
+    smda_subscription: SecretStr | None = None
+
+    @field_serializer("smda_subscription", when_used="json")
+    def dump_secret(self, v: SecretStr | None) -> str | None:
+        """Write the secret string value when serializing to json."""
+        if v is None:
+            return None
+        return v.get_secret_value()
+
+
+class UserConfig(ResettableBaseModel):
+    """The configuration file in a $HOME/.fmu directory.
+
+    Stored as config.json.
+    """
+
+    version: VersionStr
+    created_at: AwareDatetime
+    user_api_keys: UserAPIKeys
+    recent_directories: RecentDirectories
+
+    @classmethod
+    def reset(cls: type[Self]) -> Self:
+        """Resets the model to an initial state."""
+        return cls(
+            version=__version__,
+            created_at=datetime.now(UTC),
+            user_api_keys=UserAPIKeys(),
+            recent_directories=set(),
+        )
+
+    def obfuscate_secrets(self: Self) -> Self:
+        """Returns a copy of the model with obfuscated secrets.
+
+        If an API Key is:
+
+            key: SecretStr = SecretStr("secret")
+
+        we may want to serialize it to JSON as:
+
+            {key:"********"}
+
+        so that we do not serialize the actual value of the secret when, for example,
+        returning the user configuration from an API.
+        """
+        config_dict = self.model_dump()
+        # Overwrite secret keys with obfuscated keys
+        for k, v in config_dict["user_api_keys"].items():
+            if v is not None:
+                # Convert SecretStr("*********") to "*********"
+                config_dict["user_api_keys"][k] = str(v)
+        return self.model_validate(config_dict)

fmu/settings/resources/config_managers.py

@@ -0,0 +1,211 @@
+"""The generic configuration file in a .fmu directory."""
+
+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 .managers import PydanticResourceManager
+
+if TYPE_CHECKING:
+    # Avoid circular dependency for type hint in __init__ only
+    from fmu.settings._fmu_dir import (
+        FMUDirectoryBase,
+        ProjectFMUDirectory,
+        UserFMUDirectory,
+    )
+
+logger: Final = null_logger(__name__)
+
+T = TypeVar("T", bound=ResettableBaseModel)
+
+
+class ConfigManager(PydanticResourceManager[T]):
+    """Manages the .fmu configuration file."""
+
+    def __init__(self: Self, fmu_dir: FMUDirectoryBase, config: type[T]) -> None:
+        """Initializes the Config resource manager."""
+        super().__init__(fmu_dir, config)
+
+    @property
+    def relative_path(self: Self) -> Path:
+        """Returns the relative path to the config file."""
+        return Path("config.json")
+
+    def _get_dot_notation_key(
+        self: Self, config_dict: dict[str, Any], key: str, default: Any = None
+    ) -> Any:
+        """Sets the value to a dot-notation key.
+
+        Args:
+            config_dict: The configuration dictionary we are modifying (by reference)
+            key: The key to set
+            default: Value to return if key is not found. Default None
+
+        Returns:
+            The value or default
+        """
+        parts = key.split(".")
+        value = config_dict
+        for part in parts:
+            if isinstance(value, dict) and part in value:
+                value = value[part]
+            else:
+                return default
+
+        return value
+
+    def get(self: Self, key: str, default: Any = None) -> Any:
+        """Gets a configuration value by key.
+
+        Supports dot notation for nested values (e.g., "foo.bar")
+
+        Args:
+            key: The configuration key
+            default: Value to return if key is not found. Default None
+
+        Returns:
+            The configuration value or deafult
+        """
+        try:
+            config = self.load()
+
+            if "." in key:
+                return self._get_dot_notation_key(config.model_dump(), key, default)
+
+            if hasattr(config, key):
+                return getattr(config, key)
+
+            config_dict = config.model_dump()
+            return config_dict.get(key, default)
+        except FileNotFoundError as e:
+            raise FileNotFoundError(
+                f"Resource file for '{self.__class__.__name__}' not found "
+                f"at: '{self.path}' when getting key {key}"
+            ) from e
+
+    def _set_dot_notation_key(
+        self: Self, config_dict: dict[str, Any], key: str, value: Any
+    ) -> None:
+        """Sets the value to a dot-notation key.
+
+        Args:
+            config_dict: The configuration dictionary we are modifying (by reference)
+            key: The key to set
+            value: The value to set
+        """
+        parts = key.split(".")
+        target = config_dict
+
+        for part in parts[:-1]:
+            if part not in target or not isinstance(target[part], dict):
+                target[part] = {}
+            target = target[part]
+
+        target[parts[-1]] = value
+
+    def set(self: Self, key: str, value: Any) -> None:
+        """Sets a configuration value by key.
+
+        Args:
+            key: The configuration key
+            value: The value to set
+
+        Raises:
+            FileNotFoundError: If config file doesn't exist
+            ValueError: If the updated config is invalid
+        """
+        try:
+            config = self.load()
+            config_dict = config.model_dump()
+
+            if "." in key:
+                self._set_dot_notation_key(config_dict, key, value)
+            else:
+                config_dict[key] = value
+
+            updated_config = config.model_validate(config_dict)
+            self.save(updated_config)
+        except ValidationError as e:
+            raise ValueError(
+                f"Invalid value set for '{self.__class__.__name__}' with "
+                f"key '{key}', value '{value}': '{e}"
+            ) from e
+        except FileNotFoundError as e:
+            raise FileNotFoundError(
+                f"Resource file for '{self.__class__.__name__}' not found "
+                f"at: '{self.path}' when setting key {key}"
+            ) from e
+
+    def update(self: Self, updates: dict[str, Any]) -> T:
+        """Updates multiple configuration values at once.
+
+        Args:
+            updates: Dictionary of key-value pairs to update
+
+        Returns:
+            The updated Config object
+
+        Raises:
+            FileNotFoundError: If config file doesn't exist
+            ValueError: If the updates config is invalid
+        """
+        try:
+            config = self.load()
+            config_dict = config.model_dump()
+
+            flat_updates = {k: v for k, v in updates.items() if "." not in k}
+            config_dict.update(flat_updates)
+
+            for key, value in updates.items():
+                if "." in key:
+                    self._set_dot_notation_key(config_dict, key, value)
+
+                updated_config = config.model_validate(config_dict)
+            self.save(updated_config)
+        except ValidationError as e:
+            raise ValueError(
+                f"Invalid value set for '{self.__class__.__name__}' with "
+                f"updates '{updates}': '{e}"
+            ) from e
+        except FileNotFoundError as e:
+            raise FileNotFoundError(
+                f"Resource file for '{self.__class__.__name__}' not found "
+                f"at: '{self.path}' when setting updates {updates}"
+            ) from e
+
+        return updated_config
+
+    def reset(self: Self) -> T:
+        """Resets the configuration to defaults.
+
+        Returns:
+            The new default config object
+        """
+        config = self.model_class.reset()
+        self.save(config)
+        return config
+
+
+class ProjectConfigManager(ConfigManager[ProjectConfig]):
+    """Manages the .fmu configuration file in a project."""
+
+    def __init__(self: Self, fmu_dir: ProjectFMUDirectory) -> None:
+        """Initializes the ProjectConfig resource manager."""
+        super().__init__(fmu_dir, ProjectConfig)
+
+
+class UserConfigManager(ConfigManager[UserConfig]):
+    """Manages the .fmu configuration file in a user's home directory."""
+
+    def __init__(self: Self, fmu_dir: UserFMUDirectory) -> None:
+        """Initializes the UserConfig resource manager."""
+        super().__init__(fmu_dir, UserConfig)

fmu/settings/resources/managers.py

@@ -0,0 +1,96 @@
+"""Contains the base class used for interacting with resources."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Generic, Self, TypeVar
+
+from pydantic import BaseModel, ValidationError
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    # Avoid circular dependency for type hint in __init__ only
+    from fmu.settings._fmu_dir import FMUDirectoryBase
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class PydanticResourceManager(Generic[T]):
+    """Base class for managing resources represented by Pydantic models."""
+
+    def __init__(self: Self, fmu_dir: FMUDirectoryBase, model_class: type[T]) -> None:
+        """Initializes the resource manager.
+
+        Args:
+            fmu_dir: The FMUDirectory instance
+            model_class: The Pydantic model class this manager handles
+        """
+        self.fmu_dir = fmu_dir
+        self.model_class = model_class
+        self._cache: T | None = None
+
+    @property
+    def relative_path(self: Self) -> Path:
+        """Returns the path to the resource file _inside_ the .fmu directory.
+
+        Must be implemented by subclasses.
+        """
+        raise NotImplementedError
+
+    @property
+    def path(self: Self) -> Path:
+        """Returns the full path to the resource file."""
+        return self.fmu_dir.get_file_path(self.relative_path)
+
+    @property
+    def exists(self: Self) -> bool:
+        """Returns whether or not the resource exists."""
+        return self.path.exists()
+
+    def load(self: Self, force: bool = False) -> T:
+        """Loads the resources from disk and validates it as a Pydantic model.
+
+        Args:
+            force: Force a re-read even if the file is already cached
+
+        Returns:
+            Validated Pydantic model
+
+        Raises:
+            FileNotFoundError: If the resource file doesn't exist
+            ValidationError: If the data doesn't match the model schema
+        """
+        if self._cache is None or force:
+            if not self.exists:
+                raise FileNotFoundError(
+                    f"Resource file for '{self.__class__.__name__}' not found "
+                    f"at: '{self.path}'"
+                )
+
+            try:
+                content = self.fmu_dir.read_text_file(self.relative_path)
+                data = json.loads(content)
+                self._cache = self.model_class.model_validate(data)
+            except ValidationError as e:
+                raise ValueError(
+                    f"Invalid content in resource file for '{self.__class__.__name__}: "
+                    f"'{e}"
+                ) from e
+            except json.JSONDecodeError as e:
+                raise ValueError(
+                    f"Invalid JSON in resource file for '{self.__class__.__name__}': "
+                    f"'{e}'"
+                ) from e
+
+        return self._cache
+
+    def save(self: Self, model: T) -> None:
+        """Save the Pydantic model to disk.
+
+        Args:
+            model: Validated Pydantic model instance
+        """
+        json_data = model.model_dump_json(by_alias=True, indent=2)
+        self.fmu_dir.write_text_file(self.relative_path, json_data)
+        self._cache = model

fmu/settings/types.py

@@ -0,0 +1,20 @@
+"""Type annotations used in Pydantic models."""
+
+from __future__ import annotations
+
+from typing import Annotated, Self, TypeAlias
+
+from pydantic import BaseModel, Field
+
+VersionStr: TypeAlias = Annotated[
+    str, Field(pattern=r"(\d+(\.\d+){0,2}|\d+\.\d+\.[a-z0-9]+\+[a-z0-9.]+)")
+]
+
+
+class ResettableBaseModel(BaseModel):
+    """A Pydantic BaseModel that implements reset()."""
+
+    @classmethod
+    def reset(cls) -> Self:
+        """Resets the model to an initial state."""
+        raise NotImplementedError

fmu_settings-0.0.1.dist-info/METADATA

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: fmu-settings
+Version: 0.0.1
+Summary: A library for managing FMU settings
+Author-email: Equinor <fg-fmu_atlas@equinor.com>
+License: GPL-3.0
+Project-URL: Homepage, https://github.com/equinor/fmu-settings
+Project-URL: Repository, https://github.com/equinor/fmu-settings
+Project-URL: Documentation, https://github.com/equinor/fmu-settings
+Classifier: Development Status :: 3 - Alpha
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Utilities
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Natural Language :: English
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: annotated_types
+Requires-Dist: fmu-dataio
+Requires-Dist: pydantic
+Provides-Extra: dev
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Requires-Dist: pytest-xdist; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# fmu-settings
+
+[![ci](https://github.com/equinor/fmu-settings/actions/workflows/ci.yml/badge.svg)](https://github.com/equinor/fmu-settings/actions/workflows/ci.yml)
+
+**fmu-settings** is a package to manage and interface with `.fmu/`
+directories, where the FMU settings are contained.
+
+## Developing
+
+Clone and install into a virtual environment.
+
+```sh
+git clone git@github.com:equinor/fmu-settings.git
+cd fmu-settings
+# Create or source virtual/Komodo env
+pip install -U pip
+pip install -e ".[dev]"
+# Make a feature branch for your changes
+git checkout -b some-feature-branch
+```
+
+Run the tests with
+
+```sh
+pytest -n auto tests
+```
+
+Ensure your changes will pass the various linters before making a pull
+request. It is expected that all code will be typed and validated with
+mypy.
+
+```sh
+ruff check
+ruff format --check
+mypy src tests
+```
+
+See the [contributing document](CONTRIBUTING.md) for more.

fmu_settings-0.0.1.dist-info/RECORD

@@ -0,0 +1,21 @@
+fmu/__init__.py,sha256=htx6HlMme77I6pZ8U256-2B2cMJuELsu3JN3YM2Efh4,144
+fmu/settings/__init__.py,sha256=x96dVVR-2n2lYD84LGbL7W8l3-r7W_0reUTKZlE7S34,331
+fmu/settings/_fmu_dir.py,sha256=-w3cB0_2WCKYkXTmoOQtZHI_fHfCDbnzEtTF_lcYod8,10572
+fmu/settings/_init.py,sha256=5CT7tV2XHz5wuLh97XozyLiKpwogrsfjpxm2dpn7KWE,4097
+fmu/settings/_logging.py,sha256=nEdmZlNCBsB1GfDmFMKCjZmeuRp3CRlbz1EYUemc95Y,1104
+fmu/settings/_version.py,sha256=vgltXBYF55vNcC2regxjGN0_cbebmm8VgcDdQaDapWQ,511
+fmu/settings/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fmu/settings/types.py,sha256=aeXEsznBTT1YRRY_LSRqK1j2gmMmyLYYTGYl3a9fweU,513
+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=uaSAE_0y88Gvv-vM3VR5xx7yuXn9mio_8V3YC1t9wLI,2836
+fmu/settings/models/project_config.py,sha256=vImpk_rPrMEn3G9NZj83Recq9YzqAABQS7ZVUlBa0vM,1207
+fmu/settings/models/smda.py,sha256=nQ3-EI2VDRappwHgipLLXnWbEVQCsLrtJn14lES2Q6g,2639
+fmu/settings/models/user_config.py,sha256=JhMeSmWcE4GrBRkM_D5QVnUbRKfVy_XakHeKqJrYxvE,2217
+fmu/settings/resources/config_managers.py,sha256=4rA2xXS8BoNkM-RCfhJ6FNiwRGW_jTckZzpT_llkqlY,6852
+fmu/settings/resources/managers.py,sha256=t4Rp6MOSIq85iKfDHZLJxeGRj8S3SKanWHWri0p9wV8,3161
+fmu_settings-0.0.1.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+fmu_settings-0.0.1.dist-info/METADATA,sha256=_Jt3s4v_3G-lhNAd4S8ocOYZ0_KoRQEdCRCIvaQqO68,2020
+fmu_settings-0.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+fmu_settings-0.0.1.dist-info/top_level.txt,sha256=Z-FIY3pxn0UK2Wxi9IJ7fKoLSraaxuNGi1eokiE0ShM,4
+fmu_settings-0.0.1.dist-info/RECORD,,

fmu_settings-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+