floodmodeller-api 0.4.2.post1__py3-none-any.whl → 0.4.4__py3-none-any.whl

floodmodeller_api/urban1d/xsections.py

@@ -1,144 +1,147 @@
-"""
-Flood Modeller Python API
-Copyright (C) 2023 Jacobs U.K. Limited
-
-This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License
-as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
-
-This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
-of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License along with this program.  If not, see https://www.gnu.org/licenses/.
-
-If you have any query about this program or this License, please contact us at support@floodmodeller.com or write to the following
-address: Jacobs UK Limited, Flood Modeller, Cottons Centre, Cottons Lane, London, SE1 2QG, United Kingdom.
-"""
-
-from floodmodeller_api.units.helpers import _to_float, _to_int, join_n_char_ljust
-from floodmodeller_api.validation import _validate_unit
-
-from ._base import UrbanSubsection, UrbanUnit
-
-
-class XSECTION(UrbanUnit):
-    """Class to hold and process XSECTION unit type
-
-    Args:
-        name (str): Link name of the conduit, orifice, or weir. (required)
-        shape (str): cross-section shape type (see Tables D-1  or 3-1 for available shapes). (required)
-        geom1 (float): Full height of the cross-section (ft or m). (required, for shape types or "CUSTOM" or "IREGULAR)
-        geom2 (float): auxiliary parameter (width, side slopes, etc.) as listed in Table D-1. (required, applicable to shape types)
-        geom3 (float): auxiliary parameter (width, side slopes, etc.) as listed in Table D-1. (required, applicable to shape types)
-        geom4 (float):auxiliary parameter (width, side slopes, etc.) as listed in Table D-1. (required, applicable to shape types)
-        barrels (float): Barrels type  number of barrels (i.e., number of parallel pipes of equal size, slope, and roughness) associated with a conduit of shape type , or "CUSTOM" type (optional, default is 1).
-        culvert (int): Culvert code number from Table A.10 for the conduit’s inlet geometry if it is a culvert subject to possible inlet flow control.  Only an option for shape type (leave blank otherwise) (optional, default is "").
-        curve (str): Curve name of a Shape Curve in the [CURVES] section that defines how width varies with depth. (optional, applicable to shape types only)
-        tsect (str): Name of an entry in the [TRANSECTS] section that describes the cross-section geometry of an irregular channel. (required, applicable to "IREGUALAR types only)
-
-
-    Returns:
-        XSECTION: Flood Modeller XSECTION Unit class object TODO: add urban 1d in to all instances within urban 1d API
-    """
-
-    _unit = "XSECTION"
-
-    def _read(self, line):
-        unit_data = line.split()
-
-        # TODO: add functionality to read comments
-        # TODO: consider appropriate defaults
-        self.name = str(unit_data[0])
-
-        if unit_data[1] in _shape_options:
-            # Extend length of unit_data to account for missing optional arguments.
-
-            while len(unit_data) < 8:
-                unit_data.append("")
-
-            self.shape = str(unit_data[1])
-            self.geom1 = _to_float(unit_data[2], 0.0)
-            self.geom2 = _to_float(unit_data[3], 0.0)
-            self.geom3 = _to_float(unit_data[4], 0.0)
-            self.geom4 = _to_float(unit_data[5], 0.0)
-            self.barrels = _to_int(unit_data[6], 1)
-            self.culvert = _to_int(unit_data[7], "")
-
-        elif unit_data[1] == "CUSTOM":
-            while len(unit_data) < 5:
-                unit_data.append("")
-
-            self.shape = str(unit_data[1])
-            self.geom1 = _to_float(unit_data[2], "")
-            self.barrels = _to_int(unit_data[6], 1)
-
-        elif unit_data[1] == "IRREGULAR":
-            while len(unit_data) < 3:
-                unit_data.append("")
-
-            self.shape = str(unit_data[1])
-            self.tsect = str(unit_data[2])
-
-    def _write(self):
-        """Function to write a valid OUTFALL line"""
-
-        _validate_unit(self, urban=True)
-
-        # TODO:Improve indentation format when writing and include header for completeness
-
-        params1 = join_n_char_ljust(17, self.name)
-
-        if self.shape in _shape_options:
-            params2 = join_n_char_ljust(
-                15,
-                self.shape,
-                self.geom1,
-                self.geom2,
-                self.geom3,
-                self.geom4,
-                self.barrels,
-                self.culvert,
-            )
-
-        elif self.shape == "CUSTOM":
-            params2 = join_n_char_ljust(15, self.shape, self.geom1, self.barrels)
-
-        elif self.shape == "IRREGULAR":
-            params2 = join_n_char_ljust(15, self.shape, self.tsect)
-
-        else:
-            raise RuntimeError(f"{self.shape} not supported")
-
-        return params1 + params2
-
-
-class XSECTIONS(UrbanSubsection):
-    """Class to read/write the table of junctions"""
-
-    _urban_unit_class = XSECTION
-    _attribute = "xsections"
-
-
-_shape_options = [
-    "CIRCULAR",
-    "FORCE_MAIN",
-    "FILLED_CIRCULAR2",
-    "RECT_CLOSED",
-    "RECT_OPEN",
-    "TRAPEZOIDAL",
-    "TRIANGULAR",
-    "HORIZ_ELLIPSE",
-    "VERT_ELLIPSE",
-    "ARCH",
-    "PARABOLIC",
-    "POWER",
-    "RECT_TRIANGULAR",
-    "RECT_ROUND",
-    "MODBASKETHANDLE",
-    "EGG",
-    "HORSESHOE",
-    "GOTHIC",
-    "CATENARY",
-    "SEMIELLIPTICAL",
-    "BASKETHANDLE",
-    "SEMICIRCULAR",
-]
+"""
+Flood Modeller Python API
+Copyright (C) 2024 Jacobs U.K. Limited
+
+This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with this program.  If not, see https://www.gnu.org/licenses/.
+
+If you have any query about this program or this License, please contact us at support@floodmodeller.com or write to the following
+address: Jacobs UK Limited, Flood Modeller, Cottons Centre, Cottons Lane, London, SE1 2QG, United Kingdom.
+"""
+
+from floodmodeller_api.units.helpers import _to_float, _to_int, join_n_char_ljust
+from floodmodeller_api.validation import _validate_unit
+
+from ._base import UrbanSubsection, UrbanUnit
+
+
+class XSECTION(UrbanUnit):
+    """Class to hold and process XSECTION unit type
+
+    Args:
+        name (str): Link name of the conduit, orifice, or weir. (required)
+        shape (str): cross-section shape type (see Tables D-1  or 3-1 for available shapes). (required)
+        geom1 (float): Full height of the cross-section (ft or m). (required, for shape types or "CUSTOM" or "IREGULAR)
+        geom2 (float): auxiliary parameter (width, side slopes, etc.) as listed in Table D-1. (required, applicable to shape types)
+        geom3 (float): auxiliary parameter (width, side slopes, etc.) as listed in Table D-1. (required, applicable to shape types)
+        geom4 (float):auxiliary parameter (width, side slopes, etc.) as listed in Table D-1. (required, applicable to shape types)
+        barrels (float): Barrels type  number of barrels (i.e., number of parallel pipes of equal size, slope, and roughness) associated with a conduit of shape type , or "CUSTOM" type (optional, default is 1).
+        culvert (int): Culvert code number from Table A.10 for the conduit’s inlet geometry if it is a culvert subject to possible inlet flow control.  Only an option for shape type (leave blank otherwise) (optional, default is "").
+        curve (str): Curve name of a Shape Curve in the [CURVES] section that defines how width varies with depth. (optional, applicable to shape types only)
+        tsect (str): Name of an entry in the [TRANSECTS] section that describes the cross-section geometry of an irregular channel. (required, applicable to "IREGUALAR types only)
+
+
+    Returns:
+        XSECTION: Flood Modeller XSECTION Unit class object TODO: add urban 1d in to all instances within urban 1d API
+    """
+
+    _unit = "XSECTION"
+    MIN_LENGTH_OTHER = 8
+    MIN_LENGTH_CUSTOM = 5
+    MIN_LENGTH_IRREGULAR = 3
+
+    def _read(self, line):
+        unit_data = line.split()
+
+        # TODO: add functionality to read comments
+        # TODO: consider appropriate defaults
+        self.name = str(unit_data[0])
+
+        if unit_data[1] in _shape_options:
+            # Extend length of unit_data to account for missing optional arguments.
+
+            while len(unit_data) < self.MIN_LENGTH_OTHER:
+                unit_data.append("")
+
+            self.shape = str(unit_data[1])
+            self.geom1 = _to_float(unit_data[2], 0.0)
+            self.geom2 = _to_float(unit_data[3], 0.0)
+            self.geom3 = _to_float(unit_data[4], 0.0)
+            self.geom4 = _to_float(unit_data[5], 0.0)
+            self.barrels = _to_int(unit_data[6], 1)
+            self.culvert = _to_int(unit_data[7], "")
+
+        elif unit_data[1] == "CUSTOM":
+            while len(unit_data) < self.MIN_LENGTH_CUSTOM:
+                unit_data.append("")
+
+            self.shape = str(unit_data[1])
+            self.geom1 = _to_float(unit_data[2], "")
+            self.barrels = _to_int(unit_data[6], 1)
+
+        elif unit_data[1] == "IRREGULAR":
+            while len(unit_data) < self.MIN_LENGTH_IRREGULAR:
+                unit_data.append("")
+
+            self.shape = str(unit_data[1])
+            self.tsect = str(unit_data[2])
+
+    def _write(self):
+        """Function to write a valid OUTFALL line"""
+
+        _validate_unit(self, urban=True)
+
+        # TODO:Improve indentation format when writing and include header for completeness
+
+        params1 = join_n_char_ljust(17, self.name)
+
+        if self.shape in _shape_options:
+            params2 = join_n_char_ljust(
+                15,
+                self.shape,
+                self.geom1,
+                self.geom2,
+                self.geom3,
+                self.geom4,
+                self.barrels,
+                self.culvert,
+            )
+
+        elif self.shape == "CUSTOM":
+            params2 = join_n_char_ljust(15, self.shape, self.geom1, self.barrels)
+
+        elif self.shape == "IRREGULAR":
+            params2 = join_n_char_ljust(15, self.shape, self.tsect)
+
+        else:
+            raise RuntimeError(f"{self.shape} not supported")
+
+        return params1 + params2
+
+
+class XSECTIONS(UrbanSubsection):
+    """Class to read/write the table of junctions"""
+
+    _urban_unit_class = XSECTION
+    _attribute = "xsections"
+
+
+_shape_options = [
+    "CIRCULAR",
+    "FORCE_MAIN",
+    "FILLED_CIRCULAR2",
+    "RECT_CLOSED",
+    "RECT_OPEN",
+    "TRAPEZOIDAL",
+    "TRIANGULAR",
+    "HORIZ_ELLIPSE",
+    "VERT_ELLIPSE",
+    "ARCH",
+    "PARABOLIC",
+    "POWER",
+    "RECT_TRIANGULAR",
+    "RECT_ROUND",
+    "MODBASKETHANDLE",
+    "EGG",
+    "HORSESHOE",
+    "GOTHIC",
+    "CATENARY",
+    "SEMIELLIPTICAL",
+    "BASKETHANDLE",
+    "SEMICIRCULAR",
+]

floodmodeller_api/util.py

@@ -1,21 +1,119 @@
-"""
-Flood Modeller Python API
-Copyright (C) 2023 Jacobs U.K. Limited
-
-This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License
-as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
-
-This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
-of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License along with this program.  If not, see https://www.gnu.org/licenses/.
-
-If you have any query about this program or this License, please contact us at support@floodmodeller.com or write to the following
-address: Jacobs UK Limited, Flood Modeller, Cottons Centre, Cottons Lane, London, SE1 2QG, United Kingdom.
-"""
-
-import webbrowser
-
-
-def open_docs():
-    webbrowser.open_new_tab("https://api.floodmodeller.com/api/")
+"""
+Flood Modeller Python API
+Copyright (C) 2024 Jacobs U.K. Limited
+
+This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with this program.  If not, see https://www.gnu.org/licenses/.
+
+If you have any query about this program or this License, please contact us at support@floodmodeller.com or write to the following
+address: Jacobs UK Limited, Flood Modeller, Cottons Centre, Cottons Lane, London, SE1 2QG, United Kingdom.
+"""
+
+from __future__ import annotations
+
+import sys
+import webbrowser
+from functools import wraps
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from .version import __version__
+
+if TYPE_CHECKING:
+    from typing import Callable
+
+    from ._base import FMFile
+
+
+def open_docs():
+    webbrowser.open_new_tab("https://api.floodmodeller.com/api/")
+
+
+def read_file(filepath: str | Path) -> FMFile:
+    """Helper function to create an instance of an API class based on the provided filepath.
+
+    This function maps file suffixes to specific classes and returns an instance of the
+    corresponding class for handling the file.
+
+    Args:
+        filepath (Union[str, Path]): The path to the file to be read, as a string or Path object.
+
+    Returns:
+        FMFile: An instance of the class corresponding to the file type identified by the file suffix.
+
+    Raises:
+        ValueError: If the file suffix does not correspond to any supported file type.
+
+    Example:
+        .. code-block:: python
+
+            from floodmodeller_api import read_file
+
+            ief = read_file("/path/to/file.ief")
+
+
+    """
+    from . import DAT, IED, IEF, INP, LF1, LF2, XML2D, ZZN
+
+    suffix_to_class = {
+        ".ief": IEF,
+        ".dat": DAT,
+        ".ied": IED,
+        ".xml": XML2D,
+        ".zzn": ZZN,
+        ".inp": INP,
+        ".lf1": LF1,
+        ".lf2": LF2,
+    }
+    filepath = Path(filepath)
+    api_class = suffix_to_class.get(filepath.suffix.lower())
+    if api_class:
+        return api_class(filepath)
+
+    raise ValueError(f"Unsupported file type: {filepath.suffix}")
+
+
+def is_windows() -> bool:
+    return sys.platform.startswith("win")
+
+
+def handle_exception(when: str) -> Callable:
+    """Decorator factory to wrap a method with exception handling."""
+
+    def decorator(method: Callable) -> Callable:
+        @wraps(method)
+        def wrapped_method(self: FMFile, *args, **kwargs):
+            try:
+                return method(self, *args, **kwargs)
+            except Exception as e:
+                self._handle_exception(e, when)
+
+        return wrapped_method
+
+    return decorator
+
+
+class FloodModellerAPIError(Exception):
+    """Custom exception class for Flood Modeller API errors."""
+
+    def __init__(self, original_exception, when, filetype, filepath) -> None:
+        tb = original_exception.__traceback__
+        while tb.tb_next is not None:
+            tb = tb.tb_next
+        line_no = tb.tb_lineno
+        tb_path = Path(tb.tb_frame.f_code.co_filename)
+        fname = "/".join(tb_path.parts[-2:])
+
+        message = (
+            "\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"
+            f"\nAPI Error: Problem encountered when trying to {when} {filetype} file {filepath}."
+            f"\n\nDetails: {__version__}-{fname}-{line_no}"
+            f"\nMsg: {original_exception}"
+            "\n\nFor additional support, go to: https://github.com/People-Places-Solutions/floodmodeller-api"
+        )
+        super().__init__(message)