floodmodeller-api 0.4.2__py3-none-any.whl → 0.4.3__py3-none-any.whl

floodmodeller_api/urban1d/xsections.py

@@ -1,141 +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)
-
-        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,77 @@
-"""
-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 pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    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")