flood-adapt 0.3.0__py3-none-any.whl

flood_adapt/misc/database_user.py

@@ -0,0 +1,16 @@
+from abc import ABC
+
+
+class DatabaseUser(ABC):
+    """Abstract class for FloodAdapt classes that need to use / interact with the Singleton FloodAdapt database through the lazy-loading self.database property."""
+
+    _database_instance = None
+
+    @property
+    def database(self):
+        """Return the database for the object."""
+        if self._database_instance is None:
+            from flood_adapt.dbs_classes.database import Database
+
+            self._database_instance = Database()
+        return self._database_instance

flood_adapt/misc/log.py

@@ -0,0 +1,183 @@
+import logging
+import warnings
+from contextlib import contextmanager
+from pathlib import Path
+from typing import List, Optional
+
+
+class FloodAdaptLogging:
+    _DEFAULT_FORMATTER = logging.Formatter(
+        fmt="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        datefmt="%Y-%m-%d %I:%M:%S %p",
+    )
+    _root_logger = logging.getLogger("FloodAdapt")
+
+    def __init__(
+        self,
+        file_path: Optional[Path] = None,
+        loglevel_console: int = logging.WARNING,
+        loglevel_root: int = logging.INFO,
+        loglevel_files: int = logging.DEBUG,
+        formatter: logging.Formatter = _DEFAULT_FORMATTER,
+        ignore_warnings: Optional[list[type[Warning]]] = None,
+    ) -> None:
+        """Initialize the logging system for the FloodAdapt."""
+        self._formatter = formatter
+
+        self._root_logger.setLevel(loglevel_root)
+        if self._root_logger.hasHandlers():
+            self._root_logger.handlers.clear()
+
+        # Add file handler if provided
+        if file_path is not None:
+            self.add_file_handler(file_path, loglevel_files, formatter)
+
+        # Add console handler
+        console_handler = logging.StreamHandler()
+        console_handler.setLevel(loglevel_console)
+        console_handler.setFormatter(formatter)
+        self._root_logger.addHandler(console_handler)
+
+        if ignore_warnings:
+            for warn_type in ignore_warnings:
+                self.configure_warnings("ignore", category=warn_type)
+
+    @classmethod
+    def add_file_handler(
+        cls,
+        file_path: Path,
+        loglevel: int = logging.DEBUG,
+        formatter: Optional[logging.Formatter] = None,
+    ) -> None:
+        """Add a file handler to the logger that directs outputs to a the file."""
+        if not file_path:
+            raise ValueError("file_path must be provided.")
+        file_path = Path(file_path)
+
+        # check if the path is a only a filename
+        if not file_path.parents:
+            file_path = Path.cwd() / file_path
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        file_handler = logging.FileHandler(filename=file_path, mode="a")
+        file_handler.setLevel(loglevel)
+
+        formatter = formatter or cls._DEFAULT_FORMATTER
+        file_handler.setFormatter(formatter)
+
+        cls.getLogger().addHandler(file_handler)
+
+    @classmethod
+    def remove_file_handler(cls, file_path: Path) -> None:
+        """Remove a file handler from the logger, which stops sending logs to that file and closes it."""
+        for handler in cls.getLogger().handlers:
+            if isinstance(handler, logging.FileHandler) and handler.baseFilename == str(
+                file_path.resolve()
+            ):
+                handler.close()
+                cls.getLogger().removeHandler(handler)
+
+    @classmethod
+    def getLogger(
+        cls, name: Optional[str] = None, level: int = logging.INFO
+    ) -> logging.Logger:
+        """Get a logger with the specified name. If no name is provided, return the root logger.
+
+        If the logger does not exist, it is created with the specified level.
+
+        Parameters
+        ----------
+        name : str, optional
+            The name of the logger. If not provided, the root logger is returned.
+        level : int,
+            The level of the logger. The default is logging.INFO.
+
+        Returns
+        -------
+        logging.Logger
+            The logger with the specified name.
+        """
+        if name is None:
+            logger = cls._root_logger
+        else:
+            logger = logging.getLogger(f"FloodAdapt.{name}")
+        logger.setLevel(level)
+        return logger
+
+    @classmethod
+    def shutdown(cls):
+        root_logger = cls.getLogger()
+        handlers = root_logger.handlers[:]
+        for handler in handlers:
+            if isinstance(handler, logging.FileHandler):
+                handler.close()
+                root_logger.removeHandler(handler)
+        logging.shutdown()
+
+    @classmethod
+    @contextmanager
+    def to_file(
+        cls,
+        *,
+        file_path: Path,
+        loglevel: int = logging.DEBUG,
+        formatter: logging.Formatter = _DEFAULT_FORMATTER,
+    ):
+        """Open a file at filepath to write logs to. Does not affect other loggers.
+
+        When the context manager exits (via regular execution or an exception), the file is closed and the handler is removed.
+        """
+        if file_path is None:
+            raise ValueError(
+                "file_path must be provided as a key value pair: 'file_path=<file_path>'."
+            )
+        cls.add_file_handler(file_path, loglevel, formatter)
+        try:
+            yield
+        finally:
+            cls.remove_file_handler(file_path)
+
+    @classmethod
+    def _close_file_handlers(cls, logger: logging.Logger, exclude: List[Path]) -> None:
+        """Close and remove file handlers from a logger."""
+        for handler in logger.handlers[:]:
+            if (
+                isinstance(handler, logging.FileHandler)
+                and Path(handler.baseFilename) not in exclude
+            ):
+                handler.close()
+                logger.removeHandler(handler)
+
+    @classmethod
+    def close_files(cls, exclude: List[Path] = []) -> None:
+        """Close all file handlers except those in the exclude list."""
+        cls._close_file_handlers(cls.getLogger(), exclude)
+        cls._close_file_handlers(cls.getLogger("hydromt"), exclude)
+
+    @classmethod
+    def deprecation_warning(cls, version: str, reason: str):
+        """Log a deprecation warning with reason and the version that will remove it."""
+        warnings.warn(
+            f"DeprecationWarning: {reason}. This will be removed in version {version}.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+    @classmethod
+    def configure_warnings(
+        cls, action: str = "default", category: Optional[type[Warning]] = None
+    ):
+        """
+        Configure the behavior of Python warnings.
+
+        Parameters
+        ----------
+        action : str, optional
+            The action to take on warnings. Common actions include 'ignore', 'default', 'error', 'always', etc.
+            The default is 'default', which shows warnings once per triggering location.
+        category : type[Warning], optional
+            The category of warnings to configure. If not provided, all warnings are configured.
+            categories include DeprecationWarning, UserWarning, RuntimeWarning, etc.
+
+        """
+        warnings.simplefilter(action=action, category=category)

flood_adapt/misc/path_builder.py

@@ -0,0 +1,54 @@
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+from flood_adapt.config.config import Settings
+
+
+class TopLevelDir(str, Enum):
+    """Top level directories in the database."""
+
+    input = "input"
+    output = "output"
+    static = "static"
+    temp = "temp"
+
+
+class ObjectDir(str, Enum):
+    """The names for object directories at the second level of the database."""
+
+    site = "site"
+
+    benefit = "benefits"
+    event = "events"
+    strategy = "strategies"
+    measure = "measures"
+    projection = "projections"
+    scenario = "scenarios"
+    config = "config"
+
+    # buyout = "measures"
+    # elevate = "measures"
+    # floodproof = "measures"
+    # greening = "measures"
+    # floodwall = "measures"
+    # pump = "measures"
+
+
+def db_path(
+    top_level_dir: TopLevelDir = TopLevelDir.input,
+    object_dir: Optional[ObjectDir] = None,
+    obj_name: Optional[str] = None,
+) -> Path:
+    """Return an path to a database directory from arguments."""
+    rel_path = Path(top_level_dir.value)
+    if object_dir is not None:
+        if isinstance(object_dir, ObjectDir):
+            rel_path = rel_path / object_dir.value
+        else:
+            rel_path = rel_path / str(object_dir)
+
+        if obj_name is not None:
+            rel_path = rel_path / obj_name
+
+    return Settings().database_path / rel_path

flood_adapt/misc/utils.py

@@ -0,0 +1,185 @@
+import os
+import shutil
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Union
+
+from pydantic import BeforeValidator
+
+from flood_adapt.misc.path_builder import (
+    ObjectDir,
+    db_path,
+)
+
+
+@contextmanager
+def modified_environ(*remove, **update):
+    """
+    Temporarily updates the ``os.environ`` dictionary in-place.
+
+    From https://github.com/laurent-laporte-pro/stackoverflow-q2059482/blob/master/demo/environ_ctx.py
+
+    The ``os.environ`` dictionary is updated in-place so that the modification
+    is sure to work in all situations.
+
+    :param remove: Environment variables to remove.
+    :param update: Dictionary of environment variables and values to add/update.
+    """
+    env = os.environ
+    update = update or {}
+    remove = remove or []
+
+    # List of environment variables being updated or removed.
+    stomped = (set(update.keys()) | set(remove)) & set(env.keys())
+    # Environment variables and values to restore on exit.
+    update_after = {k: env[k] for k in stomped}
+    # Environment variables and values to remove on exit.
+    remove_after = frozenset(k for k in update if k not in env)
+
+    try:
+        env.update(update)
+        [env.pop(k, None) for k in remove]
+        yield
+    finally:
+        env.update(update_after)
+        [env.pop(k) for k in remove_after]
+
+
+@contextmanager
+def cd(newdir: Path):
+    prevdir = Path().cwd()
+    os.chdir(newdir)
+    try:
+        yield
+    finally:
+        os.chdir(prevdir)
+
+
+def write_finished_file(path: Path):
+    if not path.exists():
+        path.mkdir(parents=True)
+    with open(Path(path) / "finished.txt", "w") as f:
+        f.write("run finished")
+
+
+def finished_file_exists(path: Path):
+    return (Path(path) / "finished.txt").exists()
+
+
+def resolve_filepath(
+    object_dir: ObjectDir, obj_name: str, path: Path | str | os.PathLike
+) -> Path:
+    """
+    Determine whether a given path is an external file or a file in the database.
+
+    Users can set the path to a file in the database directly, meaning it will be an absolute path.
+    Users can also read the path from loading a toml file, meaning it will be a filename relative to the toml file.
+
+    Parameters
+    ----------
+    object_dir : ObjectDir
+        The directory name of the object in the database.
+    obj_name : str
+        The name of the object.
+    path : Union[Path, str, os.PathLike]
+        The path to the file, which can be an absolute path or a relative path.
+
+    Returns
+    -------
+    Path
+        The resolved path to the file.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the file does not exist in either the provided path or the database path.
+    """
+    _path = Path(path)
+    if str(_path) == _path.name:
+        # this is a filename, so it is in the database
+        src_path = db_path(object_dir=object_dir, obj_name=obj_name) / path
+    else:
+        # this is a path, so it is an external file
+        src_path = Path(path)
+    return src_path
+
+
+def save_file_to_database(
+    src_file: Path | str | os.PathLike, dst_dir: Path | str | os.PathLike
+) -> Path:
+    """Save a file to the database.
+
+    Parameters
+    ----------
+    src_file : Path | str | os.PathLike
+        Path to the file to be copied.
+    dst_dir : Path | str | os.PathLike
+        Path to the destination directory.
+
+    Returns
+    -------
+    Path
+        Path to the copied file
+
+    Raises
+    ------
+    FileNotFoundError
+        If the src_file does not exist at the given path
+    """
+    src_file = Path(src_file).resolve()
+    dst_file = Path(dst_dir).resolve() / src_file.name
+
+    if not src_file.exists():
+        raise FileNotFoundError(
+            f"Failed to find {src_file} when saving external file to the database as it does not exist."
+        )
+    if src_file == dst_file:
+        return dst_file
+    elif dst_file.exists():
+        if dst_file.suffix == ".shp":
+            for file in list(dst_file.parent.glob(f"{dst_file.stem}.*")):
+                os.remove(file)
+        else:
+            os.remove(dst_file)
+
+    dst_file.parent.mkdir(parents=True, exist_ok=True)
+    if src_file.suffix == ".shp":
+        for file in list(src_file.parent.glob(f"{src_file.stem}.*")):
+            shutil.copy2(file, dst_file.parent.joinpath(file.name))
+    else:
+        shutil.copy2(src_file, dst_file)
+
+    return dst_file
+
+
+def copy_file_to_output_dir(file_path: Path, output_dir: Path) -> Path:
+    output_dir = output_dir.resolve()
+    if file_path == output_dir / file_path.name:
+        return file_path
+    output_dir.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(file_path, output_dir)
+    return output_dir / file_path.name
+
+
+def validate_file_extension(allowed_extensions: list[str]):
+    """Validate the extension of the given path has one of the given suffixes.
+
+    Examples
+    --------
+    >>> from pydantic import BaseModel
+    >>> from pathlib import Path
+    >>> from typing import Annotated
+
+    >>> class MyClass(BaseModel):
+    >>>     csv_path: Annotated[Path, validate_file_extension([".csv"])]
+    """
+
+    def _validator(value: Union[Path, str, os.PathLike]) -> Path:
+        value = Path(value)
+        if value.suffix not in allowed_extensions:
+            raise ValueError(
+                f"Invalid file extension: {value}. Allowed extensions are {', '.join(allowed_extensions)}."
+            )
+        return value
+
+    return BeforeValidator(_validator)

flood_adapt/objects/__init__.py

@@ -0,0 +1,59 @@
+from .benefits.benefits import Benefit
+from .events.event_factory import EventFactory
+from .events.event_set import EventSet
+from .events.events import Event
+from .events.historical import HistoricalEvent
+from .events.hurricane import HurricaneEvent
+from .events.synthetic import SyntheticEvent
+from .forcing.forcing_factory import ForcingFactory
+from .measures.measure_factory import MeasureFactory
+from .measures.measures import (
+    Buyout,
+    Elevate,
+    FloodProof,
+    FloodWall,
+    GreenInfrastructure,
+    Measure,
+    MeasureType,
+    Pump,
+    SelectionType,
+)
+from .object_model import Object
+from .projections.projections import Projection
+from .scenarios.scenarios import Scenario
+from .strategies.strategies import Strategy
+
+__all__ = [
+    # Object
+    "Object",
+    # Measures
+    "MeasureFactory",
+    "Measure",
+    "MeasureType",
+    "SelectionType",
+    "MeasureType",
+    "Buyout",
+    "Elevate",
+    "FloodProof",
+    "FloodWall",
+    "GreenInfrastructure",
+    "MeasureType",
+    "Pump",
+    # Events
+    "Event",
+    "EventFactory",
+    "EventSet",
+    "SyntheticEvent",
+    "HistoricalEvent",
+    "HurricaneEvent",
+    # Forcing
+    "ForcingFactory",
+    # Projections
+    "Projection",
+    # Strategies
+    "Strategy",
+    # Scenarios
+    "Scenario",
+    # Benefits
+    "Benefit",
+]

flood_adapt/objects/benefits/benefits.py

@@ -0,0 +1,61 @@
+from typing import Optional
+
+from pydantic import BaseModel
+
+from flood_adapt.objects.object_model import Object
+
+
+class CurrentSituationModel(BaseModel):
+    """
+    The accepted input for a current situation in FloodAdapt.
+
+    Attributes
+    ----------
+    projection : str
+        The name of the projection. Should be a projection saved in the database.
+    year : int
+        The year of the current situation.
+    """
+
+    projection: str
+    year: int
+
+
+class Benefit(Object):
+    """BaseModel describing the expected variables and data types of a Benefit analysis object.
+
+    Attributes
+    ----------
+    name: str
+        The name of the benefit analysis.
+    description: str, default=""
+        The description of the benefit analysis.
+    strategy : str
+        The name of the strategy. Should be a strategy saved in the database.
+    event_set : str
+        The name of the event set. Should be an event set saved in the database.
+    projection : str
+        The name of the projection. Should be a projection saved in the database.
+    future_year : int
+        The future year for the analysis.
+    current_situation : CurrentSituationModel
+        The current situation model.
+    baseline_strategy : str
+        The name of the baseline strategy.
+    discount_rate : float
+        The discount rate for the analysis.
+    implementation_cost : Optional[float], default = None
+        The implementation cost of the strategy.
+    annual_maint_cost : Optional[float], default = None
+        The annual maintenance cost of the strategy.
+    """
+
+    strategy: str
+    event_set: str
+    projection: str
+    future_year: int
+    current_situation: CurrentSituationModel
+    baseline_strategy: str
+    discount_rate: float
+    implementation_cost: Optional[float] = None
+    annual_maint_cost: Optional[float] = None

flood_adapt/objects/events/event_factory.py

@@ -0,0 +1,135 @@
+from pathlib import Path
+from typing import Any, List
+
+import tomli
+
+from flood_adapt.objects.events.event_set import EventSet
+from flood_adapt.objects.events.events import (
+    Event,
+    Mode,
+    Template,
+)
+from flood_adapt.objects.events.historical import HistoricalEvent
+from flood_adapt.objects.events.hurricane import (
+    HurricaneEvent,
+    TranslationModel,
+)
+from flood_adapt.objects.events.synthetic import SyntheticEvent
+
+__all__ = ["TranslationModel", "EventSet"]
+
+
+class EventFactory:
+    """Factory class for creating events.
+
+    This class is used to create events based on a template.
+
+    Attributes
+    ----------
+    _EVENT_TEMPLATES : dict[str, (Event, Event)]
+        Dictionary mapping event templates to event classes and models
+    """
+
+    _EVENT_TEMPLATES = {
+        Template.Hurricane: HurricaneEvent,
+        Template.Historical: HistoricalEvent,
+        Template.Synthetic: SyntheticEvent,
+    }
+
+    @staticmethod
+    def get_event_from_template(template: Template) -> type[Event]:
+        """Get the event class corresponding to the template.
+
+        Parameters
+        ----------
+        template : str
+            Name of the event template
+
+        Returns
+        -------
+        Type[Event]
+            Event template
+        """
+        if template not in EventFactory._EVENT_TEMPLATES:
+            raise ValueError(f"Invalid event template: {template}")
+        return EventFactory._EVENT_TEMPLATES[template]
+
+    @staticmethod
+    def read_template(filepath: Path) -> Template:
+        """Get event template from toml file."""
+        if not filepath.exists():
+            raise FileNotFoundError(f"File not found: {filepath}")
+        with open(filepath, mode="rb") as fp:
+            toml = tomli.load(fp)
+        if (template := toml.get("template")) is None:
+            raise ValueError(f"Event template not found in {filepath}")
+
+        return Template(template)
+
+    @staticmethod
+    def read_mode(filepath: Path) -> Mode:
+        """Get event mode from toml file."""
+        if not filepath.exists():
+            raise FileNotFoundError(f"File not found: {filepath}")
+        with open(filepath, mode="rb") as fp:
+            toml = tomli.load(fp)
+        if toml.get("mode") is None:
+            raise ValueError(f"Event mode not found in {filepath}")
+        return Mode(toml.get("mode"))
+
+    @staticmethod
+    def load_file(toml_file: Path) -> Event:
+        """Return event object based on toml file.
+
+        Parameters
+        ----------
+        toml_file : str
+            Template name
+
+        Returns
+        -------
+        Event
+            Event object
+        """
+        mode = EventFactory.read_mode(toml_file)
+        if mode == Mode.risk:
+            event_type = EventSet
+        elif mode == Mode.single_event:
+            template = Template(EventFactory.read_template(toml_file))
+            event_type = EventFactory.get_event_from_template(template)
+        else:
+            raise ValueError(f"Invalid event mode: {mode}")
+        return event_type.load_file(toml_file)
+
+    @staticmethod
+    def load_dict(attrs: dict[str, Any] | Event) -> Event | EventSet:
+        """Return event object based on attrs dict.
+
+        Parameters
+        ----------
+        attrs : dict[str, Any]
+            Event attributes
+
+        Returns
+        -------
+        Event
+            Event object based on template
+        """
+        if isinstance(attrs, Event):
+            mode = attrs.mode
+            template = attrs.template
+        else:
+            mode = Mode(attrs.get("mode"))
+            template = Template(attrs.get("template"))
+
+        if mode == Mode.risk:
+            # TODO Load events
+            return EventSet(**attrs)
+        elif mode == Mode.single_event:
+            return EventFactory.get_event_from_template(template)(**attrs)
+        else:
+            raise ValueError(f"Invalid event mode: {mode}")
+
+    @staticmethod
+    def get_allowed_forcings(template) -> dict[str, List[str]]:
+        return EventFactory.get_event_from_template(template).get_allowed_forcings()