cht_utils 2.0.0__py3-none-any.whl

cht_utils/fileops/fileops.py

@@ -0,0 +1,344 @@
+"""Common file and directory operations using pathlib and shutil."""
+
+import shutil
+from pathlib import Path
+from typing import List, Union
+
+PathLike = Union[str, Path]
+
+
+def move(src: PathLike, dst: PathLike) -> None:
+    """Move files to a destination.
+
+    If *src* contains glob wildcards, all matching files are moved into *dst*
+    (which must be a directory). Without wildcards, *dst* may be a directory
+    or a new file name (rename).
+
+    Parameters
+    ----------
+    src : str or Path
+        Source glob pattern (e.g. ``"data/*.nc"``) or single file/directory.
+    dst : str or Path
+        Destination directory or new name.
+    """
+    src = Path(src)
+    dst = Path(dst)
+    if _has_glob(src):
+        for f in src.parent.glob(src.name):
+            target = dst / f.name
+            if target.exists():
+                if target.is_dir():
+                    shutil.rmtree(target)
+                else:
+                    target.unlink()
+            shutil.move(str(f), str(dst))
+    else:
+        if src.exists():
+            # If dst is a directory, the final target is dst/src.name
+            target = dst / src.name if dst.is_dir() else dst
+            if target.exists():
+                if target.is_dir():
+                    shutil.rmtree(target)
+                else:
+                    target.unlink()
+            shutil.move(str(src), str(dst))
+
+
+def copy(src: PathLike, dst: PathLike) -> None:
+    """Copy files or directories to a destination.
+
+    If *src* contains glob wildcards, all matching files are copied into *dst*
+    (which must be a directory). Without wildcards, *dst* may be a directory
+    or a new file name.
+
+    Parameters
+    ----------
+    src : str or Path
+        Source glob pattern or single file/directory.
+    dst : str or Path
+        Destination directory or new name.
+    """
+    src = Path(src)
+    dst = Path(dst)
+    if _has_glob(src):
+        for f in src.parent.glob(src.name):
+            _copy_single(f, dst / f.name)
+    else:
+        if not src.exists():
+            print(f"{src} does not exist")
+            return
+        if dst.is_dir():
+            _copy_single(src, dst / src.name)
+        else:
+            _copy_single(src, dst)
+
+
+def delete(src: Union[PathLike, List[PathLike]]) -> None:
+    """Delete files or directories matching glob patterns.
+
+    Handles both files (``unlink``) and directories (``rmtree``).
+    Silently skips paths that don't exist.
+
+    Parameters
+    ----------
+    src : str, Path, or list thereof
+        Glob pattern(s) or explicit path(s) to delete.
+    """
+    patterns = src if isinstance(src, list) else [src]
+    for pattern in patterns:
+        p = Path(pattern)
+        if _has_glob(p):
+            matches = list(p.parent.glob(p.name))
+        else:
+            matches = [p] if p.exists() else []
+        for f in matches:
+            try:
+                if f.is_dir():
+                    shutil.rmtree(f)
+                else:
+                    f.unlink()
+            except OSError:
+                print(f"Could not delete {f}")
+
+
+def rename(src: PathLike, dst: PathLike) -> Path:
+    """Rename a file or directory.
+
+    Works across drives on Windows (falls back to copy + delete).
+
+    Parameters
+    ----------
+    src : str or Path
+        Source path.
+    dst : str or Path
+        New name or path.
+
+    Returns
+    -------
+    Path
+        The new path.
+    """
+    src = Path(src)
+    dst = Path(dst)
+    try:
+        return src.rename(dst)
+    except OSError:
+        # Cross-drive rename on Windows
+        if src.is_dir():
+            shutil.copytree(src, dst)
+            shutil.rmtree(src)
+        else:
+            shutil.copy2(src, dst)
+            src.unlink()
+        return dst
+
+
+def mkdir(path: PathLike) -> Path:
+    """Create a directory (including parents) if it does not exist.
+
+    Parameters
+    ----------
+    path : str or Path
+        Directory path to create.
+
+    Returns
+    -------
+    Path
+        The created directory path.
+    """
+    p = Path(path)
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def touch(path: PathLike) -> Path:
+    """Create an empty file or update its modification timestamp.
+
+    Parent directories are created if needed.
+
+    Parameters
+    ----------
+    path : str or Path
+        File path.
+
+    Returns
+    -------
+    Path
+        The touched file path.
+    """
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.touch()
+    return p
+
+
+def file_size(path: PathLike) -> int:
+    """Return the size of a file in bytes.
+
+    Parameters
+    ----------
+    path : str or Path
+        File path.
+
+    Returns
+    -------
+    int
+        File size in bytes.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the file does not exist.
+    """
+    return Path(path).stat().st_size
+
+
+def list_files(
+    src: PathLike,
+    pattern: str = "*",
+    recursive: bool = False,
+    full_path: bool = True,
+) -> List[str]:
+    """List files in a directory, optionally filtered by glob pattern.
+
+    Parameters
+    ----------
+    src : str or Path
+        Directory path, or glob pattern for backward compatibility
+        (e.g. ``"data/*.nc"``).
+    pattern : str
+        Glob pattern to filter files. Defaults to ``"*"`` (all files).
+        Ignored when *src* itself contains wildcards.
+    recursive : bool
+        If ``True``, search subdirectories recursively.
+    full_path : bool
+        If ``True``, return full paths. If ``False``, return basenames.
+
+    Returns
+    -------
+    List[str]
+        Sorted list of file paths or names.
+    """
+
+    # Collapse consecutive wildcards — pathlib rejects "**" mixed with text
+    while "**" in pattern:
+        pattern = pattern.replace("**", "*")
+    p = Path(src)
+    if _has_glob(p):
+        # Legacy: src is a glob pattern like "data/*.nc"
+        name = p.name
+        while "**" in name:
+            name = name.replace("**", "*")
+        files = list(p.parent.glob(name))
+    elif recursive:
+        files = list(p.rglob(pattern))
+    else:
+        files = list(p.glob(pattern))
+    files = [f for f in files if f.is_file()]
+    if full_path:
+        return sorted(str(f) for f in files)
+    return sorted(f.name for f in files)
+
+
+def list_folders(
+    src: PathLike, pattern: str = "*", basename: bool = False
+) -> List[str]:
+    """List subdirectories, optionally filtered by glob pattern.
+
+    Parameters
+    ----------
+    src : str or Path
+        Directory path, or glob pattern for backward compatibility.
+    pattern : str
+        Glob pattern to filter folders. Defaults to ``"*"``.
+        Ignored when *src* itself contains wildcards.
+    basename : bool
+        If ``True``, return only folder names instead of full paths.
+
+    Returns
+    -------
+    List[str]
+        Sorted list of folder paths or names.
+    """
+    p = Path(src)
+    if _has_glob(p):
+        folders = list(p.parent.glob(p.name))
+    else:
+        folders = list(p.glob(pattern))
+    folders = [f for f in folders if f.is_dir()]
+    if basename:
+        return sorted(f.name for f in folders)
+    return sorted(str(f) for f in folders)
+
+
+def exists(src: PathLike) -> bool:
+    """Check if a file or directory exists.
+
+    Parameters
+    ----------
+    src : str or Path
+        Path to check.
+
+    Returns
+    -------
+    bool
+    """
+    return Path(src).exists()
+
+
+def find_replace(file_name: PathLike, old: str, new: str) -> None:
+    """Replace all occurrences of a string in a file.
+
+    Parameters
+    ----------
+    file_name : str or Path
+        File to modify in-place.
+    old : str
+        String to search for.
+    new : str
+        Replacement string.
+    """
+    p = Path(file_name)
+    p.write_text(p.read_text().replace(old, new))
+
+
+# ── Internal helpers ──────────────────────────────────────────────────
+
+
+def _has_glob(p: Path) -> bool:
+    """Check if a path contains glob wildcard characters."""
+    return any(c in str(p) for c in ("*", "?", "["))
+
+
+def _copy_single(src: Path, dst: Path) -> None:
+    """Copy a single file or directory to a destination path."""
+    if dst.exists():
+        if dst.is_dir():
+            shutil.rmtree(dst)
+        else:
+            dst.unlink()
+    if src.is_dir():
+        shutil.copytree(src, dst)
+    else:
+        shutil.copy2(src, dst)
+
+
+# ── Backward-compatible aliases ───────────────────────────────────────
+
+move_file = move
+copy_file = copy
+delete_file = delete
+delete_folder = delete
+rm = delete
+rmdir = delete
+findreplace = find_replace
+
+
+def list_all_files(src: PathLike) -> List[str]:
+    """Backward-compatible alias for ``list_files(src, recursive=True)``."""
+    return list_files(src, recursive=True)
+
+
+def list_files_recursive(src: PathLike, pattern: str = "*") -> List[str]:
+    """Backward-compatible alias for ``list_files(src, pattern, recursive=True)``."""
+    return list_files(src, pattern=pattern, recursive=True)

cht_utils/interpolation/__init__.py

@@ -0,0 +1,5 @@
+"""Spatial interpolation utilities for regular and unstructured grids."""
+
+from cht_utils.interpolation.interpolation import interp2 as interp2
+from cht_utils.interpolation.interpolation import interp2_bilinear as interp2_bilinear
+from cht_utils.interpolation.interpolation import interp3 as interp3

cht_utils/interpolation/interpolation.py

@@ -0,0 +1,152 @@
+"""Spatial interpolation utilities for regular and unstructured grids."""
+
+import numpy as np
+from scipy.interpolate import RegularGridInterpolator, griddata
+
+
+def interp2(
+    x0: np.ndarray,
+    y0: np.ndarray,
+    z0: np.ndarray,
+    x1: np.ndarray,
+    y1: np.ndarray,
+    method: str = "linear",
+) -> np.ndarray:
+    """Interpolate from a regular grid to arbitrary points.
+
+    Parameters
+    ----------
+    x0 : np.ndarray
+        1-D array of x-coordinates of the source grid.
+    y0 : np.ndarray
+        1-D array of y-coordinates of the source grid.
+    z0 : np.ndarray
+        2-D array of values on the source grid, shape ``(len(y0), len(x0))``.
+    x1 : np.ndarray
+        Target x-coordinates (1-D or 2-D).
+    y1 : np.ndarray
+        Target y-coordinates (1-D or 2-D).
+    method : str
+        Interpolation method (``"linear"``, ``"nearest"``).
+
+    Returns
+    -------
+    np.ndarray
+        Interpolated values at the target locations.
+    """
+    f = RegularGridInterpolator(
+        (y0, x0), z0, bounds_error=False, fill_value=np.nan, method=method
+    )
+    if x1.ndim > 1:
+        sz = x1.shape
+        z1 = f((y1.ravel(), x1.ravel())).reshape(sz)
+    else:
+        z1 = f((y1, x1))
+    return z1
+
+
+def interp2_bilinear(
+    xp: np.ndarray,
+    yp: np.ndarray,
+    zp: np.ndarray,
+    x: np.ndarray,
+    y: np.ndarray,
+) -> np.ndarray:
+    """Bilinear interpolation on a regular grid.
+
+    Parameters
+    ----------
+    xp : np.ndarray
+        1-D array of source x-coordinates (monotonically increasing).
+    yp : np.ndarray
+        1-D array of source y-coordinates (monotonically increasing).
+    zp : np.ndarray
+        2-D source values, shape ``(len(yp), len(xp))``.
+    x : np.ndarray
+        Target x-coordinates.
+    y : np.ndarray
+        Target y-coordinates.
+
+    Returns
+    -------
+    np.ndarray
+        Interpolated values at the target locations.
+    """
+    dx = xp[1] - xp[0]
+    dy = yp[1] - yp[0]
+
+    col = (x - xp[0]) / dx
+    row = (y - yp[0]) / dy
+
+    c0 = np.floor(col).astype(int)
+    r0 = np.floor(row).astype(int)
+    c1 = c0 + 1
+    r1 = r0 + 1
+
+    # Clip to valid range
+    c0 = np.clip(c0, 0, len(xp) - 1)
+    c1 = np.clip(c1, 0, len(xp) - 1)
+    r0 = np.clip(r0, 0, len(yp) - 1)
+    r1 = np.clip(r1, 0, len(yp) - 1)
+
+    # Fractional parts
+    dc = col - np.floor(col)
+    dr = row - np.floor(row)
+
+    z = (
+        zp[r0, c0] * (1 - dc) * (1 - dr)
+        + zp[r0, c1] * dc * (1 - dr)
+        + zp[r1, c0] * (1 - dc) * dr
+        + zp[r1, c1] * dc * dr
+    )
+    return z
+
+
+def interp3(
+    x0: np.ndarray,
+    y0: np.ndarray,
+    z0: np.ndarray,
+    x1: np.ndarray,
+    y1: np.ndarray,
+    method: str = "linear",
+) -> np.ndarray:
+    """Interpolate from unstructured or curvilinear points.
+
+    Uses :func:`scipy.interpolate.griddata` for scattered-data interpolation.
+
+    Parameters
+    ----------
+    x0 : np.ndarray
+        Source x-coordinates (1-D or 2-D).
+    y0 : np.ndarray
+        Source y-coordinates (1-D or 2-D).
+    z0 : np.ndarray
+        Source values.
+    x1 : np.ndarray
+        Target x-coordinates (1-D or 2-D).
+    y1 : np.ndarray
+        Target y-coordinates (1-D or 2-D).
+    method : str
+        Interpolation method (``"linear"``, ``"nearest"``, ``"cubic"``).
+
+    Returns
+    -------
+    np.ndarray
+        Interpolated values at the target locations.
+    """
+    if x1.ndim > 1:
+        sz = x1.shape
+        z1 = griddata(
+            (x0.ravel(), y0.ravel()),
+            z0.ravel(),
+            (x1.ravel(), y1.ravel()),
+            method=method,
+        ).reshape(sz)
+    else:
+        z1 = griddata(
+            (x0.ravel(), y0.ravel()),
+            z0.ravel(),
+            (x1, y1),
+            method=method,
+        )
+    return z1

cht_utils/maps/__init__.py

@@ -0,0 +1,2 @@
+from cht_utils.maps.flood_map import *
+from cht_utils.maps.topobathy_map import *

cht_utils/maps/fileops.py

@@ -0,0 +1,191 @@
+"""File and directory operations for copying, moving, deleting, and listing paths."""
+
+from __future__ import annotations
+
+import glob
+import logging
+import os
+import shutil
+
+logger = logging.getLogger(__name__)
+
+
+def move_file(src: str, dst: str) -> None:
+    """Move files matching a glob pattern to a destination directory.
+
+    Parameters
+    ----------
+    src : str
+        Glob pattern for source files.
+    dst : str
+        Destination directory path.
+    """
+    for full_file_name in glob.glob(src):
+        src_name = os.path.basename(full_file_name)
+        if os.path.exists(os.path.join(dst, src_name)):
+            try:
+                os.remove(os.path.join(dst, src_name))
+            except Exception:
+                logger.error(f"Could not remove file {os.path.join(dst, src_name)}")
+        try:
+            shutil.move(full_file_name, dst)
+        except Exception:
+            logger.error(f"Could not move file {full_file_name}")
+
+
+def copy_file(src: str, dst: str) -> None:
+    """Copy files matching a glob pattern to a destination directory.
+
+    Parameters
+    ----------
+    src : str
+        Glob pattern for source files.
+    dst : str
+        Destination directory path.
+    """
+    for full_file_name in glob.glob(src):
+        src_name = os.path.basename(full_file_name)
+        if os.path.exists(os.path.join(dst, src_name)):
+            os.remove(os.path.join(dst, src_name))
+        if os.path.isdir(full_file_name):
+            dstf = os.path.join(dst, os.path.basename(full_file_name))
+            shutil.copytree(full_file_name, dstf)
+        else:
+            shutil.copy(full_file_name, dst)
+
+
+def delete_file(src: str) -> None:
+    """Delete files matching a glob pattern.
+
+    Parameters
+    ----------
+    src : str
+        Glob pattern for files to delete.
+    """
+    for file_name in glob.glob(src):
+        try:
+            os.remove(src)
+        except Exception:
+            logger.error(f"Could not delete {src}")
+
+
+def rm(src: str) -> None:
+    """Remove a single file.
+
+    Parameters
+    ----------
+    src : str
+        Path to the file to remove.
+    """
+    os.remove(src)
+
+
+def mkdir(path: str) -> None:
+    """Create a directory (and parents) if it does not already exist.
+
+    Parameters
+    ----------
+    path : str
+        Directory path to create.
+    """
+    if not os.path.exists(path):
+        os.makedirs(path)
+
+
+def list_files(src: str, full_path: bool = True) -> list[str]:
+    """List files matching a glob pattern or directory listing.
+
+    Parameters
+    ----------
+    src : str
+        Glob pattern (when *full_path* is True) or directory path (when False).
+    full_path : bool
+        If True, use glob and return full paths. If False, use ``os.listdir``.
+
+    Returns
+    -------
+    list[str]
+        Sorted list of file paths or names.
+    """
+    if full_path:
+        file_list = []
+        full_list = glob.glob(src)
+        for item in full_list:
+            if os.path.isfile(item):
+                file_list.append(item)
+    else:
+        file_list = os.listdir(src)
+
+    return sorted(file_list)
+
+
+def list_folders(src: str, basename: bool = False) -> list[str]:
+    """List directories matching a glob pattern.
+
+    Parameters
+    ----------
+    src : str
+        Glob pattern.
+    basename : bool
+        If True, return only base names instead of full paths.
+
+    Returns
+    -------
+    list[str]
+        Sorted list of directory paths (or base names).
+    """
+    folder_list = []
+    full_list = glob.glob(src)
+    for item in full_list:
+        if os.path.isdir(item):
+            if basename:
+                folder_list.append(os.path.basename(item))
+            else:
+                folder_list.append(item)
+
+    return sorted(folder_list)
+
+
+def delete_folder(src: str) -> None:
+    """Recursively delete a directory tree.
+
+    Parameters
+    ----------
+    src : str
+        Path to the directory to delete.
+    """
+    try:
+        shutil.rmtree(src, ignore_errors=False, onerror=None)
+    except Exception:
+        logger.error(f"Could not delete folder {src}")
+
+
+def rmdir(src: str) -> None:
+    """Recursively delete a directory tree if it exists.
+
+    Parameters
+    ----------
+    src : str
+        Path to the directory to delete.
+    """
+    try:
+        if os.path.exists(src):
+            shutil.rmtree(src, ignore_errors=False, onerror=None)
+    except Exception:
+        logger.error(f"Could not delete folder {src}")
+
+
+def exists(src: str) -> bool:
+    """Check whether a path exists.
+
+    Parameters
+    ----------
+    src : str
+        Path to check.
+
+    Returns
+    -------
+    bool
+        True if the path exists.
+    """
+    return os.path.exists(src)