fmu-settings 0.0.1__py3-none-any.whl

fmu/__init__.py

@@ -0,0 +1,6 @@
+"""The fmu.* package namespace.
+
+Do not add anything else to this module.
+"""
+
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

fmu/settings/__init__.py

@@ -0,0 +1,12 @@
+"""The fmu-settings package."""
+
+try:
+    from ._version import version
+
+    __version__ = version
+except ImportError:
+    __version__ = version = "0.0.0"
+
+from ._fmu_dir import ProjectFMUDirectory, find_nearest_fmu_directory, get_fmu_directory
+
+__all__ = ["get_fmu_directory", "ProjectFMUDirectory", "find_nearest_fmu_directory"]

fmu/settings/_fmu_dir.py

@@ -0,0 +1,337 @@
+"""Main interface for working with .fmu directory."""
+
+from pathlib import Path
+from typing import Any, Final, Self, TypeAlias, cast
+
+from ._logging import null_logger
+from .models.project_config import ProjectConfig
+from .models.user_config import UserConfig
+from .resources.config_managers import (
+    ProjectConfigManager,
+    UserConfigManager,
+)
+
+logger: Final = null_logger(__name__)
+
+FMUConfigManager: TypeAlias = ProjectConfigManager | UserConfigManager
+
+
+class FMUDirectoryBase:
+    """Provides access to a .fmu directory and operations on its contents."""
+
+    config: FMUConfigManager
+
+    def __init__(self: Self, base_path: str | Path) -> None:
+        """Initializes access to a .fmu directory.
+
+        Args:
+            base_path: The directory containing the .fmu directory or one of its parent
+                dirs
+
+        Raises:
+            FileExistsError: If .fmu exists but is not a directory
+            FileNotFoundError: If .fmu directory doesn't exist
+            PermissionError: If lacking permissions to read/write to the directory
+        """
+        self.base_path = Path(base_path).resolve()
+        logger.debug(f"Initializing FMUDirectory from '{base_path}'")
+
+        fmu_dir = self.base_path / ".fmu"
+        if fmu_dir.exists():
+            if fmu_dir.is_dir():
+                self._path = fmu_dir
+            else:
+                raise FileExistsError(
+                    f".fmu exists at {self.base_path} but is not a directory"
+                )
+        else:
+            raise FileNotFoundError(f"No .fmu directory found at {self.base_path}")
+
+        logger.debug(f"Using .fmu directory at {self._path}")
+
+    @property
+    def path(self: Self) -> Path:
+        """Returns the path to the .fmu directory."""
+        return self._path
+
+    def get_config_value(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
+        """
+        return self.config.get(key, default)
+
+    def set_config_value(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
+        """
+        self.config.set(key, value)
+
+    def update_config(
+        self: Self, updates: dict[str, Any]
+    ) -> ProjectConfig | UserConfig:
+        """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
+        """
+        return self.config.update(updates)
+
+    def get_file_path(self: Self, relative_path: str | Path) -> Path:
+        """Gets the absolute path to a file within the .fmu directory.
+
+        Args:
+            relative_path: Path relative to the .fmu directory
+
+        Returns:
+            Absolute path to the file
+        """
+        return self.path / relative_path
+
+    def read_file(self, relative_path: str | Path) -> bytes:
+        """Reads a file from the .fmu directory.
+
+        Args:
+            relative_path: Path relative to the .fmu directory
+
+        Returns:
+            File contents as bytes
+
+        Raises:
+            FileNotFoundError: If the file doesn't exist
+        """
+        file_path = self.get_file_path(relative_path)
+        return file_path.read_bytes()
+
+    def read_text_file(self, relative_path: str | Path, encoding: str = "utf-8") -> str:
+        """Reads a text file from the .fmu directory.
+
+        Args:
+            relative_path: Path relative to the .fmu directory
+            encoding: Text encoding to use. Default utf-8
+
+        Returns:
+            File contents as string
+        """
+        file_path = self.get_file_path(relative_path)
+        return file_path.read_text(encoding=encoding)
+
+    def write_file(self, relative_path: str | Path, data: bytes) -> None:
+        """Writes bytes to a file in the .fmu directory.
+
+        Args:
+            relative_path: Path relative to the .fmu directory
+            data: Bytes to write
+        """
+        file_path = self.get_file_path(relative_path)
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        file_path.write_bytes(data)
+        logger.debug(f"Wrote {len(data)} bytes to {file_path}")
+
+    def write_text_file(
+        self, relative_path: str | Path, content: str, encoding: str = "utf-8"
+    ) -> None:
+        """Writes text to a file in the .fmu directory.
+
+        Args:
+            relative_path: Path relative to the .fmu directory
+            content: Text content to write
+            encoding: Text encoding to use. Default utf-8
+        """
+        file_path = self.get_file_path(relative_path)
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        file_path.write_text(content, encoding=encoding)
+        logger.debug(f"Wrote text file to {file_path}")
+
+    def list_files(self, subdirectory: str | Path | None = None) -> list[Path]:
+        """Lists files in the .fmu directory or a subdirectory.
+
+        Args:
+            subdirectory: Optional subdirectory to list files from
+
+        Returns:
+            List of Path objects for files (not directories)
+        """
+        base = self.get_file_path(subdirectory) if subdirectory else self.path
+        if not base.exists():
+            return []
+
+        return [p for p in base.iterdir() if p.is_file()]
+
+    def ensure_directory(self, relative_path: str | Path) -> Path:
+        """Ensures a subdirectory exists in the .fmu directory.
+
+        Args:
+            relative_path: Path relative to the .fmu directory
+
+        Returns:
+            Path to the directory
+        """
+        dir_path = self.get_file_path(relative_path)
+        dir_path.mkdir(parents=True, exist_ok=True)
+        return dir_path
+
+    def file_exists(self, relative_path: str | Path) -> bool:
+        """Checks if a file exists in the .fmu directory.
+
+        Args:
+            relative_path: Path relative to the .fmu directory
+
+        Returns:
+            True if the file exists, False otherwise
+        """
+        return self.get_file_path(relative_path).exists()
+
+
+class ProjectFMUDirectory(FMUDirectoryBase):
+    config: ProjectConfigManager
+
+    def __init__(self, base_path: str | Path) -> None:
+        """Initializes a project-based .fmu directory."""
+        self.config = ProjectConfigManager(self)
+        super().__init__(base_path)
+
+    def update_config(self: Self, updates: dict[str, Any]) -> ProjectConfig:
+        """Updates multiple configuration values at once.
+
+        Args:
+            updates: Dictionary of key-value pairs to update
+
+        Returns:
+            The updated ProjectConfig object
+
+        Raises:
+            FileNotFoundError: If config file doesn't exist
+            ValueError: If the updates config is invalid
+        """
+        return cast("ProjectConfig", super().update_config(updates))
+
+    @staticmethod
+    def find_fmu_directory(start_path: Path) -> Path | None:
+        """Searches for a .fmu directory in start_path and its parents.
+
+        Args:
+            start_path: The path to start searching from
+
+        Returns:
+            Path to the found .fmu directory or None if not found
+        """
+        current = start_path
+        # Prevent symlink loops
+        visited = set()
+
+        while current not in visited:
+            visited.add(current)
+            fmu_dir = current / ".fmu"
+
+            # Do not include $HOME/.fmu in the search
+            if fmu_dir.is_dir() and current != Path.home():
+                return fmu_dir
+
+            # We hit root
+            if current == current.parent:
+                break
+
+            current = current.parent
+
+        return None
+
+    @classmethod
+    def find_nearest(cls: type[Self], start_path: str | Path = ".") -> Self:
+        """Factory method to find and open the nearest .fmu directory.
+
+        Args:
+            start_path: Path to start searching from. Default current working director
+
+        Returns:
+            FMUDirectory instance
+
+        Raises:
+            FileNotFoundError: If no .fmu directory is found
+        """
+        start_path = Path(start_path).resolve()
+        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)
+
+
+class UserFMUDirectory(FMUDirectoryBase):
+    config: UserConfigManager
+
+    def __init__(self) -> None:
+        """Initializes a project-based .fmu directory."""
+        self.config = UserConfigManager(self)
+        super().__init__(Path.home())
+
+    def update_config(self: Self, updates: dict[str, Any]) -> UserConfig:
+        """Updates multiple configuration values at once.
+
+        Args:
+            updates: Dictionary of key-value pairs to update
+
+        Returns:
+            The updated UserConfig object
+
+        Raises:
+            FileNotFoundError: If config file doesn't exist
+            ValueError: If the updates config is invalid
+        """
+        return cast("UserConfig", super().update_config(updates))
+
+
+def get_fmu_directory(base_path: str | Path) -> ProjectFMUDirectory:
+    """Initializes access to a .fmu directory.
+
+    Args:
+        base_path: The directory containing the .fmu directory or one of its parent
+                   dirs
+
+    Returns:
+        FMUDirectory instance
+
+    Raises:
+        FileExistsError: If .fmu exists but is not a directory
+        FileNotFoundError: If .fmu directory doesn't exist
+        PermissionError: If lacking permissions to read/write to the directory
+
+    """
+    return ProjectFMUDirectory(base_path)
+
+
+def find_nearest_fmu_directory(start_path: str | Path = ".") -> ProjectFMUDirectory:
+    """Factory method to find and open the nearest .fmu directory.
+
+    Args:
+        start_path: Path to start searching from. Default current working directory
+
+    Returns:
+        FMUDirectory instance
+
+    Raises:
+        FileNotFoundError: If no .fmu directory is found
+    """
+    return ProjectFMUDirectory.find_nearest(start_path)

fmu/settings/_init.py

@@ -0,0 +1,131 @@
+"""Initializes the .fmu directory."""
+
+from pathlib import Path
+from textwrap import dedent
+from typing import Any, Final
+
+from ._fmu_dir import ProjectFMUDirectory, UserFMUDirectory
+from ._logging import null_logger
+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.
+
+    Args:
+        base_path: Base directory where .fmu should be created
+
+    Raises:
+        FileNotFoundError: If base_path doesn't exist
+        FileExistsError: If .fmu exists
+    """
+    logger.debug(f"Creating .fmu directory in '{base_path}'")
+
+    if not base_path.exists():
+        raise FileNotFoundError(
+            f"Base path '{base_path}' does not exist. Expected the root "
+            "directory of an FMU project."
+        )
+
+    fmu_dir = base_path / ".fmu"
+    if fmu_dir.exists():
+        if fmu_dir.is_dir():
+            raise FileExistsError(f"{fmu_dir} already exists")
+        raise FileExistsError(f"{fmu_dir} exists but is not a directory")
+
+    fmu_dir.mkdir()
+    logger.debug(f"Created .fmu directory at '{fmu_dir}'")
+
+
+def init_fmu_directory(
+    base_path: str | Path, config_data: ProjectConfig | dict[str, Any] | None = None
+) -> ProjectFMUDirectory:
+    """Creates and initializes a .fmu directory.
+
+    Also initializes a configuration file if configuration data is provided through the
+    function.
+
+    Args:
+        base_path: Directory where .fmu should be created
+        config_data: Optional ProjectConfig instance or dictionary with configuration
+          data
+
+    Returns:
+        Instance of FMUDirectory
+
+    Raises:
+        FileExistsError: If .fmu exists
+        FileNotFoundError: If base_path doesn't exist
+        PermissionError: If the user lacks permission to create directories
+        ValidationError: If config_data fails validationg
+    """
+    logger.debug("Initializing .fmu directory")
+    base_path = Path(base_path)
+
+    _create_fmu_directory(base_path)
+
+    fmu_dir = ProjectFMUDirectory(base_path)
+    fmu_dir.write_text_file("README", _README)
+
+    fmu_dir.config.reset()
+    if config_data:
+        if isinstance(config_data, ProjectConfig):
+            config_dict = config_data.model_dump()
+            fmu_dir.update_config(config_dict)
+        elif isinstance(config_data, dict):
+            fmu_dir.update_config(config_data)
+
+    logger.debug(f"Successfully initialized .fmu directory at '{fmu_dir}'")
+    return fmu_dir
+
+
+def init_user_fmu_directory() -> UserFMUDirectory:
+    """Creates and initializes a user's $HOME/.fmu directory.
+
+    Returns:
+        Instance of FMUDirectory
+
+    Raises:
+        FileExistsError: If .fmu exists
+        FileNotFoundError: If base_path doesn't exist
+        PermissionError: If the user lacks permission to create directories
+        ValidationError: If config_data fails validationg
+    """
+    logger.debug("Initializing .fmu directory")
+
+    _create_fmu_directory(Path.home())
+
+    fmu_dir = UserFMUDirectory()
+    fmu_dir.write_text_file("README", _USER_README)
+
+    fmu_dir.config.reset()
+    logger.debug(f"Successfully initialized .fmu directory at '{fmu_dir}'")
+    return fmu_dir

fmu/settings/_logging.py

@@ -0,0 +1,30 @@
+"""Contains the logger that should be used throughout this package."""
+
+import logging
+
+
+def null_logger(name: str) -> logging.Logger:
+    """Create and return a logger with a NullHandler.
+
+    This function creates a logger for the specified name and attaches a
+    NullHandler to it. The NullHandler prevents logging messages from being
+    automatically output to the console or other default handlers. This is
+    particularly useful in library modules where you want to provide the
+    users of the library the flexibility to configure their own logging behavior.
+
+    Args:
+        name: The name of the logger to be created. This is typically
+                    the name of the module in which the logger is
+                    created (e.g., using __name__).
+
+    Returns:
+        A logger object configured with a NullHandler.
+
+    Example:
+        # In a library module
+        logger = null_logger(__name__)
+        logger.info("This info won't be logged to the console by default.")
+    """
+    logger = logging.getLogger(name)
+    logger.addHandler(logging.NullHandler())
+    return logger

fmu/settings/_version.py

@@ -0,0 +1,21 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '0.0.1'
+__version_tuple__ = version_tuple = (0, 0, 1)

fmu/settings/models/__init__.py

@@ -0,0 +1,5 @@
+"""Contains models used in this package.
+
+Some models contained here may also be used outside this
+package.
+"""

fmu/settings/models/_enums.py

@@ -0,0 +1,34 @@
+"""Contains enumerations used in this package."""
+
+from enum import StrEnum
+
+
+class MappingType(StrEnum):
+    """The discriminator used between mappings.
+
+    Each of these types should have their own mapping class derived of some sort of
+    mapping.
+    """
+
+    fault = "fault"
+    stratigraphy = "stratigraphy"
+    well = "well"
+
+
+class RelationType(StrEnum):
+    """The kind of relation this mapping represents."""
+
+    alias = "alias"
+    child_to_parent = "child_to_parent"
+    equivalent = "equivalent"
+    fmu_to_target = "fmu_to_target"
+    predecessor_to_successor = "predecessor_to_successor"
+
+
+class DataEntrySource(StrEnum):
+    user = "user"
+    automated = "automated"
+
+
+class TargetSystem(StrEnum):
+    smda = "smda"

fmu/settings/models/_mappings.py

@@ -0,0 +1,118 @@
+"""Contains models used for representing mappings within FMU."""
+
+from pathlib import Path
+from typing import Literal
+from uuid import UUID
+
+from pydantic import BaseModel, RootModel
+
+from fmu.dataio._models.enums import Content  # type: ignore
+
+from ._enums import (
+    DataEntrySource,
+    MappingType,
+    RelationType,
+    TargetSystem,
+)
+
+
+class Source(BaseModel):
+    name: str
+    data_entry_source: DataEntrySource
+
+
+class BaseMapping(BaseModel):
+    """The base mapping containing the fields all mappings should contain.
+
+    These fields will be contained in every individual mapping entry.
+    """
+
+    source_system: str
+    target_system: TargetSystem
+    mapping_type: MappingType
+
+
+class IdentifierMapping(BaseMapping):
+    """Base class for a one-to-one or many-to-one mapping of identifiers.
+
+    This mapping represents takes some identifier from one source and correlates it to
+    an identifier in a target. Most often this target will be some official masterdata
+    store like SMDA.
+    """
+
+    source_id: str
+    target_id: str
+    target_uuid: UUID
+
+
+class StratigraphyMapping(IdentifierMapping):
+    """Represents a stratigraphy mapping.
+
+    This is a mapping from stratigraphic aliases identifiers to an official
+    identifier.
+    """
+
+    mapping_type: Literal[MappingType.stratigraphy] = MappingType.stratigraphy
+
+
+class WellMapping(IdentifierMapping):
+    """Represents a well mapping.
+
+    This is a mapping from well aliases identifiers to an official
+    identifier.
+    """
+
+    mapping_type: Literal[MappingType.well] = MappingType.well
+
+
+class FaultMapping(IdentifierMapping):
+    """Represents a fault mapping.
+
+    This is a mapping from fault aliases identifiers to an official
+    identifier.
+    """
+
+    mapping_type: Literal[MappingType.well]
+
+
+class EntityReference(BaseModel):
+    """Represents one entity we wish to related to naother entity.
+
+    This is typically an object exported by dataio.
+    """
+
+    name: str
+    uuid: UUID
+    content: Content
+    relative_path: Path
+    absolute_path: Path
+
+
+class RelationshipMapping(BaseMapping):
+    """Base class for a mapping that represents a relationship between two entities."""
+
+    source_entity: EntityReference
+    target_entity: EntityReference
+    relation_type: RelationType
+
+
+class ParentChildMapping(BaseMapping):
+    """A mapping between a child and their parent."""
+
+
+class HierarchicalMapping(RelationshipMapping):
+    """A mapping that contains a hierarchy."""
+
+
+class Mappings(BaseModel):
+    """A list of mappings under a mappings key in metadata or in a file on disk."""
+
+    items: list[BaseMapping]
+
+
+class OrderedMappings(Mappings):
+    """Items in this list imply an ordering that is important in some context."""
+
+
+MappingFile = RootModel[Mappings]
+"""Represents a list of mappings contained in a text file."""