cht_utils 2.0.0__py3-none-any.whl

cht_utils/fileio/tekal.py

@@ -0,0 +1,234 @@
+"""Read and write Delft3D Tekal ASCII files.
+
+A Tekal file consists of consecutive blocks, each containing:
+
+- Optional ``*``-prefixed comment lines
+- A block name line
+- A size line (nrows, ncols, and optionally nx, ny)
+- Data lines
+
+Example usage::
+
+    import cht_utils.fileio.tekal as tek
+
+    D = tek.tekal("myfile.tek")
+    D.info()
+    print(D)
+    M = D.read(0)  # load first block
+"""
+
+from typing import IO, List, Optional
+
+import numpy as np
+
+
+class tekalblock:
+    """A single data block within a Tekal file."""
+
+    def __init__(self) -> None:
+        self.header: List[str] = []
+        self.nhdr: Optional[int] = None
+        self.index: Optional[int] = None
+        self.name: Optional[str] = None
+        self.npts: Optional[int] = None
+        self.nvar: Optional[int] = None
+        self.nx: Optional[int] = None
+        self.ny: Optional[int] = None
+        self.data: Optional[np.ndarray] = None
+        self.tell: float = 0.0
+
+    def __str__(self) -> str:
+        return (
+            f"{self.index:5g}: nvar={self.nvar:4g} npts={self.npts:5g} "
+            f"({self.nx:5g} x{self.ny:4g}) {self.nhdr:4} '{self.name}'\n"
+        )
+
+    def strheader(self) -> str:
+        """Return a header line describing the column layout."""
+        return (
+            f"{'block':>5s}:      {'nvar':>4s}      {'npts':>5s} "
+            f"({'nx':>5s} x{'ny':>4s}) {'nhdr':>4s} '{'blockname'}'\n"
+        )
+
+    def info(self, fid: IO, index: int) -> Optional["tekalblock"]:
+        """Read block metadata (header, name, dimensions) from an open file.
+
+        Parameters
+        ----------
+        fid : IO
+            Open file handle.
+        index : int
+            Block index.
+
+        Returns
+        -------
+        tekalblock or None
+            Self if successful, ``None`` at end-of-file.
+        """
+        self.tell = fid.tell()
+
+        rec = fid.readline()
+        if len(rec) == 0:
+            return None
+
+        while rec[0] == "*":
+            self.header.append(rec)
+            rec = fid.readline()
+
+        self.index = index
+        self.name = rec.split()[0]
+        self.header.append(rec)
+        self.nhdr = len(self.header)
+
+        rec = fid.readline()
+        parts = rec.split()
+        self.npts = int(parts[0])
+        self.nvar = int(parts[1])
+        if len(parts) == 2:
+            self.nx = self.npts
+            self.ny = 1
+        else:
+            self.nx = int(parts[2])
+            self.ny = int(parts[3])
+
+        # Skip data lines
+        for _ in range(self.npts):
+            fid.readline()
+
+        return self
+
+    def load(self, fid: IO) -> np.ndarray:
+        """Load the data from this block into a 3-D numpy array.
+
+        The returned array has shape ``(nvar, nx, ny)``.
+
+        Parameters
+        ----------
+        fid : IO
+            Open file handle, sought to ``self.tell``.
+
+        Returns
+        -------
+        np.ndarray
+            Data array of shape ``(nvar, nx, ny)``.
+        """
+        # Skip header
+        rec = fid.readline()
+        while rec[0] == "*":
+            rec = fid.readline()
+
+        rec = fid.readline()
+        parts = rec.split()
+        npts = int(parts[0])
+        nvar = int(parts[1])
+        if len(parts) == 2:
+            nx, ny = npts, 1
+        else:
+            nx, ny = int(parts[2]), int(parts[3])
+
+        M = np.zeros([nvar, nx, ny])
+        for ix in range(nx):
+            for it in range(ny):
+                rec = fid.readline()
+                values = rec.split()
+                M[:, ix, it] = [float(v) for v in values[:nvar]]
+
+        self.data = M
+        return M
+
+    def check(self) -> None:
+        """Assert that all required fields are populated."""
+        assert self.header != []
+        assert self.nhdr is not None
+        assert self.name is not None
+        assert self.npts is not None
+        assert self.nvar is not None
+        assert self.nx is not None
+        assert self.ny is not None
+        assert self.data is not None
+
+    def copy(self) -> "tekalblock":
+        """Create a deep copy of this block."""
+        cp = tekalblock()
+        cp.header = self.header[:]
+        cp.nhdr = self.nhdr
+        cp.name = self.name
+        cp.npts = self.npts
+        cp.nvar = self.nvar
+        cp.nx = self.nx
+        cp.ny = self.ny
+        cp.data = self.data.copy()
+        return cp
+
+
+class tekal:
+    """Container for a Tekal file with multiple blocks.
+
+    Parameters
+    ----------
+    filename : str
+        Path to the Tekal file.
+    """
+
+    def __init__(self, filename: str) -> None:
+        self.filename = filename
+        self.blocks: List[tekalblock] = []
+
+    def append(self, block: tekalblock) -> None:
+        """Append a validated block to the file structure."""
+        block.check()
+        self.blocks.append(block)
+        self.blocks[-1].index = len(self.blocks) - 1
+
+    def __str__(self) -> str:
+        txt = self.blocks[0].strheader()
+        for block in self.blocks:
+            txt += str(block)
+        return txt
+
+    def info(self) -> None:
+        """Read metadata for all blocks (without loading data)."""
+        fid = open(self.filename, "rb")
+        index = 0
+        while True:
+            B = tekalblock()
+            result = B.info(fid, index)
+            if result is None or B.npts is None:
+                break
+            self.blocks.append(B)
+            index += 1
+        fid.close()
+
+    def read(self, index: int) -> np.ndarray:
+        """Load data from a specific block.
+
+        Parameters
+        ----------
+        index : int
+            Block index.
+
+        Returns
+        -------
+        np.ndarray
+            Data array of shape ``(nvar, nx, ny)``.
+        """
+        fid = open(self.filename, "rb")
+        fid.seek(self.blocks[index].tell)
+        M = self.blocks[index].load(fid)
+        fid.close()
+        return M
+
+    def write(self) -> None:
+        """Write all blocks to the file."""
+        with open(self.filename, "a") as fid:
+            for block in self.blocks:
+                block.check()
+                fid.write("".join(block.header))
+                if block.ny == 1:
+                    fid.write(f"{block.npts:g} {block.nvar:g}\n")
+                else:
+                    fid.write(f"{block.npts:g} {block.nvar:g} {block.ny:g}\n")
+                for it in range(block.ny):
+                    for ix in range(block.nx):
+                        row = " ".join(f"{v:f}" for v in block.data[:, ix, it])
+                        fid.write(row + "\n")

cht_utils/fileio/xml.py

@@ -0,0 +1,184 @@
+"""XML serialization and deserialization with type conversion.
+
+Supports reading/writing Python objects and dictionaries as XML, with
+optional type attributes (``float``, ``int``, ``datetime``) for automatic
+value conversion.
+"""
+
+import urllib.request
+import xml.etree.ElementTree as ET
+from datetime import datetime
+from typing import IO, Any
+
+
+class XMLObject:
+    """Marker base class for XML-deserialized objects."""
+
+    pass
+
+
+def write_node(file: IO, node: Any, nspaces: int) -> None:
+    """Recursively write a node (dict or object) to an XML file.
+
+    Parameters
+    ----------
+    file : IO
+        Open file handle.
+    node : dict or object
+        Node to serialize.
+    nspaces : int
+        Current indentation level.
+    """
+    node_dict = node if isinstance(node, dict) else node.__dict__
+    spaces = " " * nspaces
+
+    for key, children in node_dict.items():
+        for child in children:
+            if isinstance(child, dict) or (
+                not isinstance(child, dict) and not hasattr(child, "value")
+            ):
+                if hasattr(child, "value"):
+                    _write_leaf(file, spaces, key, child)
+                else:
+                    file.write(f"{spaces}<{key}>\n")
+                    write_node(file, child, nspaces + 2)
+                    file.write(f"{spaces}</{key}>\n")
+            else:
+                _write_leaf(file, spaces, key, child)
+
+
+def _write_leaf(file: IO, spaces: str, key: str, node: Any) -> None:
+    """Write a leaf node with optional type attribute."""
+    if isinstance(node.value, int):
+        attr = ' type="int"'
+        val = str(node.value)
+    elif isinstance(node.value, float):
+        attr = ' type="float"'
+        val = str(node.value)
+    else:
+        attr = ""
+        val = node.value
+    file.write(f"{spaces}<{key}{attr}>{val}</{key}>\n")
+
+
+def obj2xml(obj: Any, file_name: str) -> None:
+    """Serialize a Python object to an XML file.
+
+    Parameters
+    ----------
+    obj : Any
+        Object whose ``__dict__`` will be serialized.
+    file_name : str
+        Output file path.
+    """
+    with open(file_name, "w") as f:
+        f.write('<?xml version="1.0"?>\n<root>\n')
+        write_node(f, obj, 2)
+        f.write("</root>\n")
+
+
+def dict2xml(xml_dict: dict, file_name: str) -> None:
+    """Serialize a dictionary to an XML file.
+
+    Parameters
+    ----------
+    xml_dict : dict
+        Dictionary to serialize.
+    file_name : str
+        Output file path.
+    """
+    with open(file_name, "w") as f:
+        f.write('<?xml version="1.0"?>\n<root>\n')
+        write_node(f, xml_dict, 2)
+        f.write("</root>\n")
+
+
+def xml2obj(file_name: str) -> Any:
+    """Deserialize an XML file (local or URL) to a Python object.
+
+    Parameters
+    ----------
+    file_name : str
+        Local file path or HTTP(S) URL.
+
+    Returns
+    -------
+    Any
+        Dynamically typed Python object tree.
+    """
+    if file_name.startswith("http"):
+        with urllib.request.urlopen(file_name) as f:
+            tree = ET.parse(f)
+            xml_root = tree.getroot()
+    else:
+        xml_root = ET.parse(file_name).getroot()
+    return _xml2py(xml_root)
+
+
+def get_value(file_name: str, tag: str) -> Any:
+    """Read a single value from an XML file by tag path.
+
+    Parameters
+    ----------
+    file_name : str
+        XML file path.
+    tag : str
+        XPath-style tag (e.g. ``"section/param"``).
+
+    Returns
+    -------
+    Any
+        The value, with type conversion applied if a ``type`` attribute exists.
+    """
+    xml_root = ET.parse(file_name).getroot()
+    node = xml_root.findall(tag)[0]
+    val = node.text
+    if node.attrib and "type" in node.attrib:
+        val = _convert_value(node.text, node.attrib["type"])
+    return val
+
+
+def _convert_value(text: str, type_name: str) -> Any:
+    """Convert a string value based on a type name."""
+    if type_name == "float":
+        return float(text)
+    elif type_name == "int":
+        return int(text)
+    elif type_name == "datetime":
+        return datetime.strptime(text, "%Y%m%d %H%M%S")
+    return text
+
+
+def _xml2py(node: ET.Element) -> Any:
+    """Recursively convert an XML element to a Python object."""
+    name = node.tag
+    pytype = type(name, (object,), {})
+    pyobj = pytype()
+
+    for attr in node.attrib:
+        setattr(pyobj, attr, node.get(attr))
+
+    if node.text and node.text.strip() not in ("", "\n"):
+        setattr(pyobj, "text", node.text)
+        setattr(pyobj, "value", node.text)
+        if node.attrib and "type" in node.attrib:
+            type_name = node.attrib["type"]
+            if type_name == "float":
+                lst = node.text.split(",")
+                pyobj.value = (
+                    float(node.text) if len(lst) == 1 else [float(s) for s in lst]
+                )
+            elif type_name == "int":
+                if "," in node.text:
+                    pyobj.value = [int(s) for s in node.text.split(",")]
+                else:
+                    pyobj.value = int(node.text)
+            elif type_name == "datetime":
+                pyobj.value = datetime.strptime(node.text, "%Y%m%d %H%M%S")
+
+    for cn in node:
+        if not hasattr(pyobj, cn.tag):
+            setattr(pyobj, cn.tag, [])
+        getattr(pyobj, cn.tag).append(_xml2py(cn))
+
+    return pyobj

cht_utils/fileio/yaml.py

@@ -0,0 +1,39 @@
+"""YAML file read/write utilities."""
+
+from typing import Any, Dict, Optional
+
+import yaml
+
+
+def dict2yaml(file_name: str, dct: Dict[str, Any], sort_keys: bool = False) -> None:
+    """Write a dictionary to a YAML file.
+
+    Parameters
+    ----------
+    file_name : str
+        Output file path.
+    dct : Dict[str, Any]
+        Dictionary to serialize.
+    sort_keys : bool
+        Whether to sort keys alphabetically.
+    """
+    yaml_string = yaml.dump(dct, sort_keys=sort_keys)
+    with open(file_name, "w") as f:
+        f.write(yaml_string)
+
+
+def yaml2dict(file_name: str) -> Optional[Dict[str, Any]]:
+    """Read a YAML file into a dictionary.
+
+    Parameters
+    ----------
+    file_name : str
+        Input file path.
+
+    Returns
+    -------
+    Dict[str, Any] or None
+        Parsed dictionary, or ``None`` for empty files.
+    """
+    with open(file_name, "r") as f:
+        return yaml.load(f, Loader=yaml.FullLoader)

cht_utils/fileops/__init__.py

@@ -0,0 +1,25 @@
+"""File and directory operations."""
+
+# Core API
+from cht_utils.fileops.fileops import copy as copy
+
+# Backward-compatible aliases
+from cht_utils.fileops.fileops import copy_file as copy_file
+from cht_utils.fileops.fileops import delete as delete
+from cht_utils.fileops.fileops import delete_file as delete_file
+from cht_utils.fileops.fileops import delete_folder as delete_folder
+from cht_utils.fileops.fileops import exists as exists
+from cht_utils.fileops.fileops import file_size as file_size
+from cht_utils.fileops.fileops import find_replace as find_replace
+from cht_utils.fileops.fileops import findreplace as findreplace
+from cht_utils.fileops.fileops import list_all_files as list_all_files
+from cht_utils.fileops.fileops import list_files as list_files
+from cht_utils.fileops.fileops import list_files_recursive as list_files_recursive
+from cht_utils.fileops.fileops import list_folders as list_folders
+from cht_utils.fileops.fileops import mkdir as mkdir
+from cht_utils.fileops.fileops import move as move
+from cht_utils.fileops.fileops import move_file as move_file
+from cht_utils.fileops.fileops import rename as rename
+from cht_utils.fileops.fileops import rm as rm
+from cht_utils.fileops.fileops import rmdir as rmdir
+from cht_utils.fileops.fileops import touch as touch