floodmodeller-api 0.5.0.post1__py3-none-any.whl → 0.5.2__py3-none-any.whl

floodmodeller_api/urban1d/xsections.py

@@ -1,6 +1,6 @@
 """
 Flood Modeller Python API
-Copyright (C) 2024 Jacobs U.K. Limited
+Copyright (C) 2025 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.
@@ -14,7 +14,7 @@ If you have any query about this program or this License, please contact us at s
 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.units._helpers import join_n_char_ljust, to_float, to_int
 from floodmodeller_api.validation import _validate_unit
 
 from ._base import UrbanSubsection, UrbanUnit
@@ -31,13 +31,13 @@ class XSECTION(UrbanUnit):
         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 "").
+        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
+        XSECTION: Flood Modeller XSECTION Unit class object
     """
 
     _unit = "XSECTION"
@@ -48,8 +48,6 @@ class XSECTION(UrbanUnit):
     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:
@@ -59,20 +57,20 @@ class XSECTION(UrbanUnit):
                 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], "")
+            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)
+            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:
@@ -86,8 +84,6 @@ class XSECTION(UrbanUnit):
 
         _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:
@@ -109,7 +105,8 @@ class XSECTION(UrbanUnit):
             params2 = join_n_char_ljust(15, self.shape, self.tsect)
 
         else:
-            raise RuntimeError(f"{self.shape} not supported")
+            msg = f"{self.shape} not supported"
+            raise RuntimeError(msg)
 
         return params1 + params2
 

floodmodeller_api/util.py

@@ -1,6 +1,6 @@
 """
 Flood Modeller Python API
-Copyright (C) 2024 Jacobs U.K. Limited
+Copyright (C) 2025 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.
@@ -18,7 +18,7 @@ from __future__ import annotations
 
 import sys
 import webbrowser
-from functools import wraps
+from functools import cache, wraps
 from pathlib import Path
 from typing import TYPE_CHECKING
 
@@ -58,7 +58,7 @@ def read_file(filepath: str | Path) -> FMFile:
 
 
     """
-    from . import DAT, IED, IEF, INP, LF1, LF2, XML2D, ZZN
+    from . import DAT, IED, IEF, INP, LF1, LF2, XML2D, ZZN, ZZX
     from .hydrology_plus import HydrologyPlusExport
 
     suffix_to_class = {
@@ -67,6 +67,7 @@ def read_file(filepath: str | Path) -> FMFile:
         ".ied": IED,
         ".xml": XML2D,
         ".zzn": ZZN,
+        ".zzx": ZZX,
         ".inp": INP,
         ".lf1": LF1,
         ".lf2": LF2,
@@ -77,13 +78,27 @@ def read_file(filepath: str | Path) -> FMFile:
     if api_class:
         return api_class(filepath)
 
-    raise ValueError(f"Unsupported file type: {filepath.suffix}")
+    msg = f"Unsupported file type: {filepath.suffix}"
+    raise ValueError(msg)
 
 
+@cache
 def is_windows() -> bool:
     return sys.platform.startswith("win")
 
 
+def get_associated_file(original_file: Path, new_suffix: str) -> Path:
+    new_file = original_file.with_suffix(new_suffix)
+    if not new_file.exists():
+        msg = (
+            f"Error: Could not find associated {new_suffix} file."
+            f" Ensure that the {original_file.suffix} results"
+            f" have an associated {new_suffix} file with matching name."
+        )
+        raise FileNotFoundError(msg)
+    return new_file
+
+
 def handle_exception(when: str) -> Callable:
     """Decorator factory to wrap a method with exception handling."""
 
@@ -103,7 +118,7 @@ def handle_exception(when: str) -> Callable:
 class FloodModellerAPIError(Exception):
     """Custom exception class for Flood Modeller API errors."""
 
-    def __init__(self, original_exception, when, filetype, filepath) -> None:
+    def __init__(self, original_exception, when, filetype, filepath: Path | None = None) -> None:
         tb = original_exception.__traceback__
         while tb.tb_next is not None:
             tb = tb.tb_next
@@ -111,9 +126,11 @@ class FloodModellerAPIError(Exception):
         tb_path = Path(tb.tb_frame.f_code.co_filename)
         fname = "/".join(tb_path.parts[-2:])
 
+        end_of_str = f"{filepath}" if filepath is not None else "from blank"
+
         message = (
             "\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"
-            f"\nAPI Error: Problem encountered when trying to {when} {filetype} file {filepath}."
+            f"\nAPI Error: Problem encountered when trying to {when} {filetype} file {end_of_str}."
             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"

floodmodeller_api/validation/parameters.py

@@ -1,6 +1,6 @@
 """
 Flood Modeller Python API
-Copyright (C) 2024 Jacobs U.K. Limited
+Copyright (C) 2025 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.
@@ -201,10 +201,10 @@ parameter_options = {
         "type": "value-match",
         "options": ["RECTANGLE", "CYLINDER", "SQUARE", "I-BEAM"],
     },
-    # Pier_faces is an optional parameters
+    # Pier_faces is an optional parameter
     "pier_faces": {
         "type": "value-match",
-        "options": ["", "STREAMLINE", "SEMICIRCLE", "TRIANGLE", "DIAPHRAGM"],
+        "options": ["", "STREAMLINE", "SEMICIRCLE", "TRIANGLE", "DIAPHRAGM", "DIA"],
     },
     "soffit_shape": {
         "type": "value-match",
@@ -657,4 +657,8 @@ parameter_options = {
         "type": "type-match",
         "options": (float, int),
     },
+    "labels": {
+        "type": "list-string-length",
+        "max_length": 12,
+    },
 }

floodmodeller_api/validation/urban_parameters.py

@@ -1,6 +1,6 @@
 """
 Flood Modeller Python API
-Copyright (C) 2024 Jacobs U.K. Limited
+Copyright (C) 2025 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.
@@ -44,9 +44,7 @@ urban_parameter_options = {
         "options": ["INTENSITY", "VOLUME", "CUMULATIVE"],
     },
     "interval": {
-        # TODO: UPDATE TO CONSIDER - decimal hours or hours:minutes format (e.g., 0:15 for 15-minute readings). search for presence of ";" during _read maybe?
         # try turing to float else keep as string
-        # TODO: add new a type of match called RegEx match for example "[0-9]:[0-9]",
         "type": "type-match",
         "options": (float, int, str),
     },
@@ -200,7 +198,6 @@ urban_parameter_options = {
         "options": (type(None), int),
     },
     "culvert": {
-        # TODO: str added to allow case when optional parameter not provided (and so is ""). Update to improve handling,
         "type": "type-match",
         "options": (type(None), int, str),
     },

floodmodeller_api/validation/validation.py

@@ -1,6 +1,6 @@
 """
 Flood Modeller Python API
-Copyright (C) 2024 Jacobs U.K. Limited
+Copyright (C) 2025 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.
@@ -23,9 +23,8 @@ def _validate_unit(unit, urban=False):
     param_validation_dict = {}
     all_valid = True
     for param in dir(unit):
-        options = (
-            parameter_options if not urban else urban_parameter_options
-        )  # define which dictionary to use
+        # define which dictionary to use
+        options = parameter_options if not urban else urban_parameter_options
 
         if param in options:
             value = getattr(unit, param)
@@ -41,7 +40,8 @@ def _validate_unit(unit, urban=False):
                 if not value[0]
             ],
         )
-        raise ValueError(f"One or more parameters in {repr(unit)} are invalid:\n     {errors}")
+        msg = f"One or more parameters in {unit!r} are invalid:\n     {errors}"
+        raise ValueError(msg)
 
 
 def _validate_parameter(param, value):  # noqa: C901, PLR0911, PLR0912
@@ -87,6 +87,12 @@ def _validate_parameter(param, value):  # noqa: C901, PLR0911, PLR0912
             f'-> Exceeds {param["max_length"]} characters',
         )
 
+    if param["type"] == "list-string-length":
+        return (
+            all(len(item) <= param["max_length"] for item in value),
+            f'-> Contains labels exceeding {param["max_length"]} characters',
+        )
+
     if param["type"] == "dict-match":
         for key, rule in param["options"].items():
             if key not in value:

floodmodeller_api/version.py

@@ -1 +1 @@
-__version__ = "0.5.0.post1"
+__version__ = "0.5.2"

floodmodeller_api/xml2d.py

@@ -1,6 +1,6 @@
 """
 Flood Modeller Python API
-Copyright (C) 2024 Jacobs U.K. Limited
+Copyright (C) 2025 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.
@@ -17,7 +17,7 @@ address: Jacobs UK Limited, Flood Modeller, Cottons Centre, Cottons Lane, London
 from __future__ import annotations
 
 import io
-import os
+import logging
 import time
 from copy import deepcopy
 from pathlib import Path
@@ -205,12 +205,9 @@ class XML2D(FMFile):
 
     def _validate(self):
         try:
-            self._xsdschema.assert_(self._xmltree)
+            self._xsdschema.assert_(self._xmltree)  # noqa: PT009
         except AssertionError as err:
-            msg = (
-                f"XML Validation Error for {repr(self)}:\n"
-                f"     {err.args[0].replace(self._ns, '')}"
-            )
+            msg = f"XML Validation Error for {self!r}:\n     {err.args[0].replace(self._ns, '')}"
             raise ValueError(msg) from err
 
     def _recursive_update_xml(  # noqa: C901, PLR0912
@@ -220,11 +217,10 @@ class XML2D(FMFile):
         parent_key,
         list_idx=None,
     ):
-        # TODO: Handle removing params
-
         for key, item in new_dict.items():
             if key in self._multi_value_keys and not isinstance(item, list):
-                raise Exception(f"Element: '{key}' must be added as list")
+                msg = f"Element: '{key}' must be added as list"
+                raise Exception(msg)
             if parent_key == "ROOT":
                 parent = self._xmltree.getroot()
             else:
@@ -294,7 +290,8 @@ class XML2D(FMFile):
         from_list=False,
     ):
         if add_key in self._multi_value_keys and not isinstance(add_item, list) and not from_list:
-            raise Exception(f"Element: '{add_key}' must be added as list")
+            msg = f"Element: '{add_key}' must be added as list"
+            raise Exception(msg)
         if isinstance(add_item, dict):
             new_element = etree.SubElement(parent, f"{self._ns}{add_key}")
             for key, item in add_item.items():
@@ -336,6 +333,10 @@ class XML2D(FMFile):
                     f".//{self._w3_schema}*[@name='{add_key}']",
                 )
 
+            if schema_elem is None:
+                msg = f"Schema element for key '{add_key}' not found in XSD."
+                raise ValueError(msg)
+
             if schema_elem.tag.endswith("attribute"):
                 parent.set(add_key, str(add_item))
 
@@ -501,20 +502,15 @@ class XML2D(FMFile):
 
         """
 
-        # TODO:
-        # - Clean up the lf code?
-        # - Remove or sort out get results
-
         self.range_function = range_function
         self.range_settings = range_settings if range_settings else {}
 
         if self._filepath is None:
-            raise UserWarning(
-                "xml2D must be saved to a specific filepath before simulate() can be called.",
-            )
+            msg = "xml2D must be saved to a specific filepath before simulate() can be called."
+            raise UserWarning(msg)
         if precision.upper() == "DEFAULT":
             precision = "SINGLE"  # defaults to single precision
-            for _, domain in self.domains.items():
+            for domain in self.domains.values():
                 if domain["run_data"].get("double_precision") == "required":
                     precision = "DOUBLE"
                     break
@@ -525,14 +521,12 @@ class XML2D(FMFile):
         else:
             _enginespath = enginespath
             if not Path(_enginespath).exists():
-                raise Exception(
-                    f"Flood Modeller non-default engine path not found! {str(_enginespath)}",
-                )
+                msg = f"Flood Modeller non-default engine path not found! {_enginespath!s}"
+                raise Exception(msg)
 
         # checking if all schemes used are fast, if so will use FAST.exe
-        # TODO: Add in option to choose to use or not to use if you can
         is_fast = True
-        for _, domain in self.domains.items():
+        for domain in self.domains.values():
             if domain["run_data"]["scheme"] != "FAST":
                 is_fast = False
                 break
@@ -545,7 +539,8 @@ class XML2D(FMFile):
             isis2d_fp = str(Path(_enginespath, "ISIS2d_DP.exe"))
 
         if not Path(isis2d_fp).exists():
-            raise Exception(f"Flood Modeller engine not found! Expected location: {isis2d_fp}")
+            msg = f"Flood Modeller engine not found! Expected location: {isis2d_fp}"
+            raise Exception(msg)
 
         console_output = console_output.lower()
         run_command = (
@@ -554,9 +549,9 @@ class XML2D(FMFile):
         stdout = DEVNULL if console_output == "simple" else None
 
         if method.upper() == "WAIT":
-            print("Executing simulation ... ")
+            logging.info("Executing simulation ... ")
             # execute simulation
-            process = Popen(run_command, cwd=os.path.dirname(self._filepath), stdout=stdout)
+            process = Popen(run_command, cwd=Path(self._filepath).parent, stdout=stdout)
 
             # progress bar based on log files:
             if console_output == "simple":
@@ -571,9 +566,9 @@ class XML2D(FMFile):
             self._interpret_exit_code(exitcode, raise_on_failure)
 
         elif method.upper() == "RETURN_PROCESS":
-            print("Executing simulation ...")
+            logging.info("Executing simulation ...")
             # execute simulation
-            return Popen(run_command, cwd=os.path.dirname(self._filepath), stdout=stdout)
+            return Popen(run_command, cwd=Path(self._filepath).parent, stdout=stdout)
 
         return None
 
@@ -584,7 +579,8 @@ class XML2D(FMFile):
             floodmodeller_api.LF2 class object
         """
         if not self._log_path.exists():
-            raise FileNotFoundError("Log file (LF2) not found")
+            msg = "Log file (LF2) not found"
+            raise FileNotFoundError(msg)
 
         return LF2(self._log_path)
 
@@ -636,4 +632,4 @@ class XML2D(FMFile):
 
         if raise_on_failure and exitcode != self.GOOD_EXIT_CODE:
             raise Exception(msg)
-        print(msg)
+        logging.info(msg)

floodmodeller_api/xml2d_template.py

@@ -1,6 +1,6 @@
 """
 Flood Modeller Python API
-Copyright (C) 2024 Jacobs U.K. Limited
+Copyright (C) 2025 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.