floodmodeller-api 0.5.0.post1__tar.gz → 0.5.2__tar.gz

{floodmodeller_api-0.5.0.post1 → floodmodeller_api-0.5.2}/LICENSE.txt

@@ -1,5 +1,5 @@
 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.

{floodmodeller_api-0.5.0.post1 → floodmodeller_api-0.5.2}/MANIFEST.in

@@ -2,8 +2,8 @@ include license.txt
 include code-of-conduct.md
 include requirements.txt
 include floodmodeller_api/xsd_backup.xml
-include floodmodeller_api/test/test_data/*
 include floodmodeller_api/toolbox/gui/*
+recursive-include floodmodeller_api/test/test_data *
 recursive-include floodmodeller_api *.dll
 recursive-include floodmodeller_api *.so
 recursive-include floodmodeller_api *.so.5

{floodmodeller_api-0.5.0.post1/floodmodeller_api.egg-info → floodmodeller_api-0.5.2}/PKG-INFO

@@ -1,10 +1,10 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: floodmodeller_api
-Version: 0.5.0.post1
+Version: 0.5.2
 Summary: Extends the functionality of Flood Modeller to python users
 Author: Jacobs
 Author-email: joe.pierce@jacobs.com
-License: GNU General Public License V3. Copyright (C) 2024 Jacobs U.K. Limited.
+License: GNU General Public License V3. Copyright (C) 2025 Jacobs U.K. Limited.
 Project-URL: API Documentation, https://api.floodmodeller.com/api/
 Project-URL: Flood Modeller Homepage, https://www.floodmodeller.com/
 Project-URL: Contact & Support, https://www.floodmodeller.com/contact
@@ -19,8 +19,19 @@ Requires-Dist: shapely==2.*
 Requires-Dist: scipy==1.*
 Requires-Dist: freezegun==1.*
 Requires-Dist: requests>2.23
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: license
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: summary
 
-![FM Logo](https://raw.githubusercontent.com/People-Places-Solutions/floodmodeller-api/main/docs/source/_static/flood-modeller-logo-hero-image.png)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/People-Places-Solutions/floodmodeller-api/main/docs/source/_static/flood-modeller-logo-hero-image-dark.png">
+  <img alt="FM Logo" src="https://raw.githubusercontent.com/People-Places-Solutions/floodmodeller-api/main/docs/source/_static/flood-modeller-logo-hero-image.png">
+</picture>
 
 
 [![PyPI Latest Release](https://img.shields.io/pypi/v/floodmodeller-api.svg)](https://pypi.org/project/floodmodeller-api/)
@@ -37,7 +48,10 @@ Requires-Dist: requests>2.23
 
 This python package is designed to be used in conjunction with your installation of Flood Modeller to provide users with a set of tools to extend the capabilities of Flood Modeller and build into automated workflows.
 
-![API Overview](https://raw.githubusercontent.com/People-Places-Solutions/floodmodeller-api/main/docs/source/getting_started/api_overview_small.png)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/People-Places-Solutions/floodmodeller-api/main/docs/source/getting_started/api_overview_dark.png">
+  <img alt="API Overview" src="https://raw.githubusercontent.com/People-Places-Solutions/floodmodeller-api/main/docs/source/getting_started/api_overview.png">
+</picture>
 
 ## Installation
 You can install the floodmodeller_api package from PyPI with the following command:
@@ -46,7 +60,7 @@ You can install the floodmodeller_api package from PyPI with the following comma
 pip install floodmodeller-api
 ```
 
-Python 3.9 or greater is required.
+Python 3.10 or greater is required.
 
 Once you have installed floodmodeller_api to your python environment, you can import the package with:
 

{floodmodeller_api-0.5.0.post1 → floodmodeller_api-0.5.2}/README.md

@@ -1,4 +1,7 @@
-![FM Logo](https://raw.githubusercontent.com/People-Places-Solutions/floodmodeller-api/main/docs/source/_static/flood-modeller-logo-hero-image.png)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/People-Places-Solutions/floodmodeller-api/main/docs/source/_static/flood-modeller-logo-hero-image-dark.png">
+  <img alt="FM Logo" src="https://raw.githubusercontent.com/People-Places-Solutions/floodmodeller-api/main/docs/source/_static/flood-modeller-logo-hero-image.png">
+</picture>
 
 
 [![PyPI Latest Release](https://img.shields.io/pypi/v/floodmodeller-api.svg)](https://pypi.org/project/floodmodeller-api/)
@@ -15,7 +18,10 @@
 
 This python package is designed to be used in conjunction with your installation of Flood Modeller to provide users with a set of tools to extend the capabilities of Flood Modeller and build into automated workflows.
 
-![API Overview](https://raw.githubusercontent.com/People-Places-Solutions/floodmodeller-api/main/docs/source/getting_started/api_overview_small.png)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/People-Places-Solutions/floodmodeller-api/main/docs/source/getting_started/api_overview_dark.png">
+  <img alt="API Overview" src="https://raw.githubusercontent.com/People-Places-Solutions/floodmodeller-api/main/docs/source/getting_started/api_overview.png">
+</picture>
 
 ## Installation
 You can install the floodmodeller_api package from PyPI with the following command:
@@ -24,7 +30,7 @@ You can install the floodmodeller_api package from PyPI with the following comma
 pip install floodmodeller-api
 ```
 
-Python 3.9 or greater is required.
+Python 3.10 or greater is required.
 
 Once you have installed floodmodeller_api to your python environment, you can import the package with:
 

floodmodeller_api-0.5.2/floodmodeller_api/__init__.py

@@ -0,0 +1,19 @@
+import logging
+import sys
+
+from .dat import DAT
+from .ied import IED
+from .ief import IEF
+from .inp import INP
+from .logs import LF1, LF2
+from .util import read_file
+from .version import __version__
+from .xml2d import XML2D
+from .zz import ZZN, ZZX
+
+logging.basicConfig(
+    stream=sys.stdout,
+    level=logging.INFO,
+    format="%(asctime)s - %(levelname)s - %(message)s",
+    datefmt="%H:%M:%S",
+)

{floodmodeller_api-0.5.0.post1 → floodmodeller_api-0.5.2}/floodmodeller_api/_base.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,6 +18,7 @@ from __future__ import annotations
 
 """ Holds the base file class for API file classes """
 
+import logging
 from pathlib import Path
 from typing import NoReturn
 
@@ -33,25 +34,26 @@ from .util import FloodModellerAPIError, handle_exception
 class FMFile(Jsonable):
     """Base class for all Flood Modeller File types"""
 
-    _filetype: str | None = None
-    _suffix: str | None = None
+    _filetype: str
+    _suffix: str
     MAX_DIFF = 25
+    ENCODING = "cp1252"
 
     def __init__(self, filepath: str | Path | None = None, **kwargs):
         if filepath is not None:
             self._filepath = Path(filepath)
             # * Add check or fix for path lengths greater than DOS standard length of 260 characters
 
-            if not self._filepath.suffix.lower() == self._suffix:
-                raise TypeError(
-                    f"Given filepath does not point to a {self._filetype} file. Please point to the full path for a {self._filetype} file",
-                )
+            if self._filepath.suffix.lower() != self._suffix:
+                msg = f"Given filepath does not point to a {self._filetype} file. Please point to the full path for a {self._filetype} file"
+                raise TypeError(msg)
             if not self._filepath.exists():
-                raise FileNotFoundError(
+                msg = (
                     f"{self._filetype} file does not exist! If you are wanting to create a new {self._filetype}, initiate the class without a given "
                     f"filepath to create a new blank {self._filetype} or point the filepath of an existing {self._filetype} to use as a template, "
-                    f"then use the .save() method to save to a new filepath",
+                    f"then use the .save() method to save to a new filepath"
                 )
+                raise FileNotFoundError(msg)
             # If the file is not a ZZN file, then perform a backup
             # This performs a conditional back up, only copying the file if an equivalent copy doesn't already exist
             if self._filetype != "ZZN":
@@ -60,6 +62,17 @@ class FMFile(Jsonable):
                 # Add the file object as a property to expose the restore method
                 self.file = file
 
+    @property
+    def filepath(self) -> Path:
+        if not hasattr(self, "_filepath"):
+            msg = "Object has no filepath."
+            raise AttributeError(msg)
+        return self._filepath
+
+    @property
+    def filetype(self) -> str:
+        return self._filetype
+
     def __repr__(self):
         filepath = "<in_memory>" if not hasattr(self, "_filepath") else self._filepath
         return f"<floodmodeller_api Class: {self._filetype}(filepath={filepath})>"
@@ -73,59 +86,65 @@ class FMFile(Jsonable):
     def _update(self):
         """Updates the existing self._filetype based on any altered attributes"""
         if self._filepath is None:
-            raise UserWarning(
-                f"{self._filetype} must be saved to a specific filepath before update() can be called.",
-            )
+            msg = f"{self._filetype} must be saved to a specific filepath before update() can be called."
+            raise UserWarning(msg)
 
         string = self._write()
-        with open(self._filepath, "w") as _file:
+        with open(self._filepath, "w", encoding=self.ENCODING) as _file:
             _file.write(string)
-        print(f"{self._filetype} File Updated!")
+        logging.info("%s File Updated!", self._filepath)
 
     def _save(self, filepath):
         filepath = Path(filepath).absolute()
-        if not filepath.suffix.lower() == self._suffix:
-            raise TypeError(
-                f'Given filepath does not point to a filepath suffixed "{self._suffix}". Please point to the full path to save the {self._filetype} file',
-            )
+        if filepath.suffix.lower() != self._suffix:
+            msg = f'Given filepath does not point to a filepath suffixed "{self._suffix}". Please point to the full path to save the {self._filetype} file'
+            raise TypeError(msg)
 
         if not filepath.parent.exists():
             Path.mkdir(filepath.parent)
 
         string = self._write()
-        with open(filepath, "w") as _file:
+        with open(filepath, "w", encoding=self.ENCODING) as _file:
             _file.write(string)
         self._filepath = filepath  # Updates the filepath attribute to the given path
 
-        print(f"{self._filetype} File Saved to: {filepath}")
+        logging.info("%s File Saved to: %s", self._filetype, filepath)
 
     @handle_exception(when="compare")
-    def _diff(self, other, force_print=False):
+    def _diff(self, other, force_print=False) -> None:
+        def _format_diff(diff_list, max_items=None) -> str:
+            return "\n".join(
+                f"  {name}:  {reason}"
+                for name, reason in (diff_list[:max_items] if max_items else diff_list)
+            )
+
         if self._filetype != other._filetype:
-            raise TypeError("Cannot compare objects of different filetypes")
+            msg = "Cannot compare objects of different filetypes"
+            raise TypeError(msg)
         diff = self._get_diff(other)
         if diff[0]:
-            print("No difference, files are equivalent")
-        else:
-            print(f"Files not equivalent, {len(diff[1])} difference(s) found:")
-            if len(diff[1]) > self.MAX_DIFF and not force_print:
-                print(f"[Showing first {self.MAX_DIFF} differences...] ")
-                print(
-                    "\n".join(
-                        [f"  {name}:  {reason}" for name, reason in diff[1][: self.MAX_DIFF]],
-                    ),
-                )
-                print("\n...To see full list of all differences add force_print=True")
-            else:
-                print("\n".join([f"  {name}:  {reason}" for name, reason in diff[1]]))
+            logging.info("No difference, files are equivalent")
+            return
+        differences = (
+            f"[Showing first {self.MAX_DIFF} differences...]\n"
+            f"{_format_diff(diff[1], self.MAX_DIFF)}\n"
+            "...To see full list of all differences add force_print=True"
+            if len(diff[1]) > self.MAX_DIFF and not force_print
+            else _format_diff(diff[1])
+        )
+        logging.info("Files not equivalent, %s difference(s) found:\n%s", len(diff[1]), differences)
 
     def _get_diff(self, other):
         return self.__eq__(other, return_diff=True)  # pylint: disable=unnecessary-dunder-call
 
     def _handle_exception(self, err, when) -> NoReturn:
-        raise FloodModellerAPIError(err, when, self._filetype, self._filepath) from err
+        filepath_or_none = self._filepath if hasattr(self, "_filepath") else None
+        raise FloodModellerAPIError(err, when, self._filetype, filepath_or_none) from err
 
     def __eq__(self, other, return_diff=False):
+        if not isinstance(other, FMFile):
+            return NotImplemented if not return_diff else (False, ["Type mismatch"])
+
         result = True
         diff = []
         try:

{floodmodeller_api-0.5.0.post1 → floodmodeller_api-0.5.2}/floodmodeller_api/backup.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,6 +17,7 @@ address: Jacobs UK Limited, Flood Modeller, Cottons Centre, Cottons Lane, London
 from __future__ import annotations
 
 import filecmp
+import logging
 import re
 import tempfile
 from datetime import datetime
@@ -60,6 +61,8 @@ class BackupControl(Jsonable):
         backup.clear_backup()
     """
 
+    ENCODING = "cp1252"
+
     def __init__(self):
         """
         Initialises a new BackUp object.
@@ -80,11 +83,15 @@ class BackupControl(Jsonable):
         # Create the backup directory if it doesn't exist
         if not self.backup_dir.exists():
             self.backup_dir.mkdir()
-            print(f"{self.__class__.__name__}: Initialised backup directory at {self.backup_dir}")
+            logging.info(
+                "%s: Initialised backup directory at %s",
+                self.__class__.__name__,
+                self.backup_dir,
+            )
 
         # Create the backup CSV file if it doesn't exist
         if not self.backup_csv_path.exists():
-            with open(self.backup_csv_path, "w") as f:
+            with open(self.backup_csv_path, "w", encoding=self.ENCODING) as f:
                 f.write("path,file_id,dttm\n")
 
     def clear_backup(self, file_id="*"):
@@ -191,11 +198,11 @@ class File(BackupControl):
     """
 
     def __init__(self, path: str | Path = "", from_json: bool = False, **args):
-        # TODO: Make protected properties so they can't be manipulated
         self.path = Path(path)
-        # Check  if the file exists
+        # Check if the file exists
         if not self.path.exists():
-            raise OSError("File not found!")
+            msg = "File not found!"
+            raise OSError(msg)
         self.ext = self.path.suffix
         self.dttm_str = datetime.now().strftime("%Y-%m-%d-%H-%M-%S")
         self._generate_file_id()
@@ -211,7 +218,6 @@ class File(BackupControl):
         Generate the file's unique identifier as using a hash of the absolute file path
         """
         # hash the absolute path becuase the same file name / directroy structure may be mirrored across projects
-        # TODO: Use a function that produces a shorter has to make interpretation of the directory easier
         fp_bytes = str(self.path.absolute()).encode()
         self.file_id = sha1(fp_bytes).hexdigest()
 
@@ -231,9 +237,8 @@ class File(BackupControl):
         backup_filepath = Path(self.backup_dir, self.backup_filename)
         copy(self.path, backup_filepath)
         # Log an entry to the csv to make it easy to find the file
-        # TODO: Only log file_id and poath, don't log duplicate lines. Needs to be fast so it doesn't slow FMFile down
-        log_str = f"{str(self.path)},{self.file_id},{self.dttm_str}\n"
-        with open(self.backup_csv_path, "a") as f:
+        log_str = f"{self.path!s},{self.file_id},{self.dttm_str}\n"
+        with open(self.backup_csv_path, "a", encoding=self.ENCODING) as f:
             f.write(log_str)
 
     def list_backups(self) -> list:
@@ -258,8 +263,6 @@ class File(BackupControl):
         if len(backups) == 0 or not filecmp.cmp(self.path, backups[0].path):
             self._make_backup()
         # If the file doesn't match the last backup then do a back up
-        # TODO: Use FloodModeller API implemented equivalence testing. This is implemented at a higher level than FMFile where this method is called.
-        # TODO: Return the file path?
 
     def clear_backup(self):
         """