ryan-tools 26.10.18.9__py3-none-any.whl

culvert_results/__init__.py

@@ -0,0 +1 @@
+"""Maintained TUFLOW culvert-result wrappers bundled with ryan-tools."""

culvert_results/combine_culvert_maximums.py

@@ -0,0 +1,106 @@
+# ryan-scripts\TUFLOW-python\culvert_results\combine_culvert_maximums.py
+"""Wrapper Script: Merge TUFLOW Culvert Maximums.
+
+This script acts as a mutable wrapper for `tuflow_culverts_merge.main_processing`.
+It combines culvert maximums (and raw data) from multiple CSV files.
+Users can edit the hard-coded constants in this file to control include data types and export format,
+or use command-line arguments to override these settings.
+"""
+
+from pathlib import Path
+from typing import Literal
+
+WRAPPER_VERSION = "2026-08-02.1"
+
+CONSOLE_LOG_LEVEL = "INFO"  # or "DEBUG"
+INCLUDE_DATA_TYPES: tuple[str, ...] = ("Nmx", "Cmx", "Chan", "ccA", "RLL_Qmx", "EOF")
+EXPORT_MODE: Literal["excel", "parquet", "both"] = "excel"
+WORKING_DIR: Path = Path(__file__).absolute().parent
+# Optional explicit folder roots to scan. If left empty, the wrapper scans WORKING_DIR recursively.
+PATHS_TO_PROCESS: tuple[Path, ...] = ()
+# WORKING_DIR: Path = Path(r"E:\path\to\custom\directory")
+
+import argparse
+
+from ryan_library.functions.wrapper_utils import (
+    CommonWrapperOptions,
+    add_common_cli_arguments,
+    change_working_directory,
+    parse_common_cli_arguments,
+    pause_console,
+    print_wrapper_banner,
+)
+from ryan_library.orchestrators.tuflow.tuflow_culverts_merge import main_processing
+
+
+def main(
+    *,
+    console_log_level: str | None = None,
+    include_data_types: tuple[str, ...] | None = None,
+    locations_to_include: tuple[str, ...] | None = None,
+    paths_to_process: tuple[Path, ...] | None = None,
+    working_directory: Path | None = None,
+) -> int:
+    """Main entry point to merge culvert maximums; double-clickable.
+
+    This function sets up the environment and calls 'main_processing'.
+    It allows users to default settings via constants while retaining CLI capabilities.
+
+    Args:
+        console_log_level: Overrides the CONSOLE_LOG_LEVEL constant.
+        include_data_types: Overrides the INCLUDE_DATA_TYPES constant.
+        locations_to_include: Overrides the locations filter.
+        paths_to_process: Explicit folder roots to scan for result files.
+        working_directory: Overrides the default WORKING_DIR.
+    """
+    print_wrapper_banner(wrapper_file=Path(__file__), wrapper_version=WRAPPER_VERSION)
+
+    script_dir: Path = working_directory or WORKING_DIR
+    if not change_working_directory(target_dir=script_dir):
+        return 1
+
+    effective_console_log_level: str = console_log_level or CONSOLE_LOG_LEVEL
+    effective_data_types: list[str] = list(include_data_types or INCLUDE_DATA_TYPES)
+    effective_export_mode: Literal["excel", "parquet", "both"] = EXPORT_MODE
+    effective_paths_to_process: list[Path] = list(paths_to_process or PATHS_TO_PROCESS or (script_dir,))
+
+    main_processing(
+        paths_to_process=effective_paths_to_process,
+        include_data_types=effective_data_types,
+        console_log_level=effective_console_log_level,
+        locations_to_include=locations_to_include,
+        export_mode=effective_export_mode,
+    )
+    return 0
+
+
+def _parse_cli_arguments() -> CommonWrapperOptions:
+    """Parse command-line arguments to override script defaults.
+
+    Returns:
+        CommonWrapperOptions: Parsed and processed common arguments.
+    """
+    parser = argparse.ArgumentParser(
+        description="Merge TUFLOW culvert maximums. Command-line options override the script defaults."
+    )
+    add_common_cli_arguments(parser=parser)
+    args: argparse.Namespace = parser.parse_args()
+    return parse_common_cli_arguments(args=args)
+
+
+if __name__ == "__main__":
+    common_options: CommonWrapperOptions = _parse_cli_arguments()
+    result: int = main(
+        console_log_level=common_options.console_log_level,
+        include_data_types=common_options.data_types,
+        locations_to_include=common_options.locations_to_include,
+        working_directory=common_options.working_directory,
+    )
+    print_wrapper_banner(
+        wrapper_file=Path(__file__),
+        wrapper_version=WRAPPER_VERSION,
+        leading_blank_line=True,
+    )
+    if not common_options.no_pause:
+        pause_console()
+    raise SystemExit(result)

culvert_results/combine_culvert_timeseries.py

@@ -0,0 +1,105 @@
+# ryan-scripts\TUFLOW-python\culvert_results\combine_culvert_timeseries.py
+"""Wrapper Script: Combine TUFLOW Culvert Timeseries.
+
+This script acts as a mutable wrapper for `tuflow_culverts_timeseries.main_processing`.
+It combines culvert timeseries data (e.g., flow vs time) from multiple CSV files.
+Users can edit the hard-coded constants in this file to control data types and export format,
+or use command-line arguments to override these settings.
+"""
+
+from pathlib import Path
+from typing import Literal
+
+WRAPPER_VERSION = "2026-08-02.1"
+
+CONSOLE_LOG_LEVEL = "INFO"
+INCLUDE_DATA_TYPES: tuple[str, ...] = ("Q", "V", "H", "CF", "Chan", "EOF")
+EXPORT_MODE: Literal["excel", "parquet", "both"] = "excel"
+WORKING_DIR: Path = Path(__file__).absolute().parent
+# Optional explicit folder roots to scan. If left empty, the wrapper scans WORKING_DIR recursively.
+PATHS_TO_PROCESS: tuple[Path, ...] = ()
+# WORKING_DIR: Path = Path(r"E:\path\to\custom\directory")
+
+import argparse
+
+from ryan_library.functions.wrapper_utils import (
+    CommonWrapperOptions,
+    add_common_cli_arguments,
+    change_working_directory,
+    parse_common_cli_arguments,
+    pause_console,
+    print_wrapper_banner,
+)
+from ryan_library.orchestrators.tuflow.tuflow_culverts_timeseries import main_processing
+
+
+def main(
+    *,
+    console_log_level: str | None = None,
+    include_data_types: tuple[str, ...] | None = None,
+    locations_to_include: tuple[str, ...] | None = None,
+    paths_to_process: tuple[Path, ...] | None = None,
+    working_directory: Path | None = None,
+) -> int:
+    """Main entry point to combine culvert timeseries; double-clickable.
+
+    This function initializes the environment and calls `main_processing`.
+    It uses constants defined in this file (e.g., INCLUDE_DATA_TYPES) as default values.
+
+    Args:
+        console_log_level: Overrides the CONSOLE_LOG_LEVEL constant.
+        include_data_types: Overrides the INCLUDE_DATA_TYPES constant.
+        locations_to_include: Overrides the locations filter.
+        paths_to_process: Explicit folder roots to scan for result files.
+        working_directory: Overrides the default WORKING_DIR.
+    """
+    print_wrapper_banner(wrapper_file=Path(__file__), wrapper_version=WRAPPER_VERSION)
+
+    script_dir: Path = working_directory or WORKING_DIR
+    if not change_working_directory(target_dir=script_dir):
+        return 1
+
+    effective_console_log_level: str = console_log_level or CONSOLE_LOG_LEVEL
+    effective_data_types: list[str] = list(include_data_types or INCLUDE_DATA_TYPES)
+    effective_export_mode: Literal["excel", "parquet", "both"] = EXPORT_MODE
+    effective_paths_to_process: list[Path] = list(paths_to_process or PATHS_TO_PROCESS or (script_dir,))
+    main_processing(
+        paths_to_process=effective_paths_to_process,
+        include_data_types=effective_data_types,
+        console_log_level=effective_console_log_level,
+        locations_to_include=locations_to_include,
+        export_mode=effective_export_mode,
+    )
+    return 0
+
+
+def _parse_cli_arguments() -> CommonWrapperOptions:
+    """Parse command-line arguments to override script defaults.
+
+    Returns:
+        CommonWrapperOptions: Parsed and processed common arguments.
+    """
+    parser = argparse.ArgumentParser(
+        description="Combine culvert timeseries exports. Command-line options override the script defaults."
+    )
+    add_common_cli_arguments(parser=parser)
+    args: argparse.Namespace = parser.parse_args()
+    return parse_common_cli_arguments(args=args)
+
+
+if __name__ == "__main__":
+    common_options: CommonWrapperOptions = _parse_cli_arguments()
+    result: int = main(
+        console_log_level=common_options.console_log_level,
+        include_data_types=common_options.data_types,
+        locations_to_include=common_options.locations_to_include,
+        working_directory=common_options.working_directory,
+    )
+    print_wrapper_banner(
+        wrapper_file=Path(__file__),
+        wrapper_version=WRAPPER_VERSION,
+        leading_blank_line=True,
+    )
+    if not common_options.no_pause:
+        pause_console()
+    raise SystemExit(result)

culvert_results/create_mean_culvert_peak_report.py

@@ -0,0 +1,111 @@
+# ryan-scripts\TUFLOW-python\culvert_results\create_mean_culvert_peak_report.py
+"""Wrapper Script: Culvert Mean Peak Reports.
+
+This script acts as a mutable wrapper for `run_culvert_mean_report`.
+It generates a summary report calculating MEAN peak values across multiple durations for culverts.
+Users can edit the hard-coded constants in this file to control data types and raw output,
+or use command-line arguments to override these settings.
+"""
+
+from pathlib import Path
+
+WRAPPER_VERSION = "2026-08-02.1"
+
+CONSOLE_LOG_LEVEL = "INFO"  # or "DEBUG"
+# Toggle the specific culvert data types to collect. Leave empty to accept the library defaults.
+INCLUDED_DATA_TYPES: tuple[str, ...] = ("Nmx", "Cmx", "Chan", "ccA", "RLL_Qmx", "EOF")
+# Toggle the export of the raw culvert-maximums sheet (may be extremely large).
+EXPORT_RAW_MAXIMUMS: bool = False
+# Change the working directory
+WORKING_DIR: Path = Path(__file__).absolute().parent
+# Optional explicit folder roots to scan. If left empty, the wrapper scans WORKING_DIR recursively.
+PATHS_TO_PROCESS: tuple[Path, ...] = ()
+# WORKING_DIR: Path = Path(r"E:\path\to\custom\directory")
+
+import argparse
+
+from ryan_library.functions.wrapper_utils import (
+    CommonWrapperOptions,
+    add_common_cli_arguments,
+    change_working_directory,
+    parse_common_cli_arguments,
+    pause_console,
+    print_wrapper_banner,
+)
+from ryan_library.orchestrators.tuflow.tuflow_culverts_mean import run_culvert_mean_report
+
+
+def main(
+    *,
+    console_log_level: str | None = None,
+    include_data_types: tuple[str, ...] | None = None,
+    locations_to_include: tuple[str, ...] | None = None,
+    paths_to_process: tuple[Path, ...] | None = None,
+    working_directory: Path | None = None,
+) -> int:
+    """Main entry point for culvert mean peak reporting.
+
+    This function initializes the environment and calls `run_culvert_mean_report`.
+    It resolves configuration by prioritizing CLI arguments, then falling back to the
+    hard-coded constants in this script.
+
+    Args:
+        console_log_level: Overrides the CONSOLE_LOG_LEVEL constant.
+        include_data_types: Overrides the INCLUDED_DATA_TYPES constant.
+        locations_to_include: Overrides the LOCATIONS_TO_INCLUDE (implicit) settings.
+        paths_to_process: Explicit folder roots to scan for result files.
+        working_directory: Overrides the default WORKING_DIR.
+    """
+    print_wrapper_banner(wrapper_file=Path(__file__), wrapper_version=WRAPPER_VERSION)
+    script_directory: Path = working_directory or WORKING_DIR
+
+    if not change_working_directory(target_dir=script_directory):
+        return 1
+
+    to_include_data_types: tuple[str, ...] | None = include_data_types or INCLUDED_DATA_TYPES or None
+    effective_console_log_level: str = console_log_level or CONSOLE_LOG_LEVEL
+    effective_locations: tuple[str, ...] | None = locations_to_include
+    effective_paths_to_process: tuple[Path, ...] | None = paths_to_process or PATHS_TO_PROCESS or None
+
+    run_culvert_mean_report(
+        script_directory=script_directory,
+        paths_to_process=effective_paths_to_process,
+        log_level=effective_console_log_level,
+        include_data_types=to_include_data_types,
+        locations_to_include=effective_locations,
+        export_raw=EXPORT_RAW_MAXIMUMS,
+    )
+
+    return 0
+
+
+def _parse_cli_arguments() -> CommonWrapperOptions:
+    """Parse command-line arguments to override script defaults.
+
+    Returns:
+        CommonWrapperOptions: Parsed and processed common arguments.
+    """
+    parser = argparse.ArgumentParser(
+        description="Create culvert mean peak reports. Command-line options override the script defaults."
+    )
+    add_common_cli_arguments(parser=parser)
+    args: argparse.Namespace = parser.parse_args()
+    return parse_common_cli_arguments(args=args)
+
+
+if __name__ == "__main__":
+    common_options: CommonWrapperOptions = _parse_cli_arguments()
+    result: int = main(
+        console_log_level=common_options.console_log_level,
+        include_data_types=common_options.data_types,
+        locations_to_include=common_options.locations_to_include,
+        working_directory=common_options.working_directory,
+    )
+    print_wrapper_banner(
+        wrapper_file=Path(__file__),
+        wrapper_version=WRAPPER_VERSION,
+        leading_blank_line=True,
+    )
+    if not common_options.no_pause:
+        pause_console()
+    raise SystemExit(result)

culvert_results/create_median_culvert_peak_report.py

@@ -0,0 +1,111 @@
+# ryan-scripts\TUFLOW-python\culvert_results\create_median_culvert_peak_report.py
+"""Wrapper Script: Culvert Median Peak Reports.
+
+This script acts as a mutable wrapper for `run_culvert_median_report`.
+It generates a summary report calculating MEDIAN peak values across multiple durations for culverts.
+Users can edit the hard-coded constants in this file to control data types and raw output,
+or use command-line arguments to override these settings.
+"""
+
+from pathlib import Path
+
+WRAPPER_VERSION = "2026-08-02.1"
+
+CONSOLE_LOG_LEVEL = "INFO"  # or "DEBUG"
+# Toggle the specific culvert data types to collect. Leave empty to accept the library defaults.
+INCLUDED_DATA_TYPES: tuple[str, ...] = ("Nmx", "Cmx", "Chan", "ccA", "RLL_Qmx", "EOF")
+# Toggle the export of the raw culvert-maximums sheet (may be extremely large).
+EXPORT_RAW_MAXIMUMS: bool = False
+# Change the working directory
+WORKING_DIR: Path = Path(__file__).absolute().parent
+# Optional explicit folder roots to scan. If left empty, the wrapper scans WORKING_DIR recursively.
+PATHS_TO_PROCESS: tuple[Path, ...] = ()
+# WORKING_DIR: Path = Path(r"E:\path\to\custom\directory")
+
+import argparse
+
+from ryan_library.functions.wrapper_utils import (
+    CommonWrapperOptions,
+    add_common_cli_arguments,
+    change_working_directory,
+    parse_common_cli_arguments,
+    pause_console,
+    print_wrapper_banner,
+)
+from ryan_library.orchestrators.tuflow.tuflow_culverts_mean import run_culvert_median_report
+
+
+def main(
+    *,
+    console_log_level: str | None = None,
+    include_data_types: tuple[str, ...] | None = None,
+    locations_to_include: tuple[str, ...] | None = None,
+    paths_to_process: tuple[Path, ...] | None = None,
+    working_directory: Path | None = None,
+) -> int:
+    """Main entry point for culvert median peak reporting.
+
+    This function initializes the environment and calls `run_culvert_median_report`.
+    It resolves configuration by prioritizing CLI arguments, then falling back to the
+    hard-coded constants in this script.
+
+    Args:
+        console_log_level: Overrides the CONSOLE_LOG_LEVEL constant.
+        include_data_types: Overrides the INCLUDED_DATA_TYPES constant.
+        locations_to_include: Overrides the LOCATIONS_TO_INCLUDE (implicit) settings.
+        paths_to_process: Explicit folder roots to scan for result files.
+        working_directory: Overrides the default WORKING_DIR.
+    """
+    print_wrapper_banner(wrapper_file=Path(__file__), wrapper_version=WRAPPER_VERSION)
+    script_directory: Path = working_directory or WORKING_DIR
+
+    if not change_working_directory(target_dir=script_directory):
+        return 1
+
+    to_include_data_types: tuple[str, ...] | None = include_data_types or INCLUDED_DATA_TYPES or None
+    effective_console_log_level: str = console_log_level or CONSOLE_LOG_LEVEL
+    effective_locations: tuple[str, ...] | None = locations_to_include
+    effective_paths_to_process: tuple[Path, ...] | None = paths_to_process or PATHS_TO_PROCESS or None
+
+    run_culvert_median_report(
+        script_directory=script_directory,
+        paths_to_process=effective_paths_to_process,
+        log_level=effective_console_log_level,
+        include_data_types=to_include_data_types,
+        locations_to_include=effective_locations,
+        export_raw=EXPORT_RAW_MAXIMUMS,
+    )
+
+    return 0
+
+
+def _parse_cli_arguments() -> CommonWrapperOptions:
+    """Parse command-line arguments to override script defaults.
+
+    Returns:
+        CommonWrapperOptions: Parsed and processed common arguments.
+    """
+    parser = argparse.ArgumentParser(
+        description="Create culvert median peak reports. Command-line options override the script defaults."
+    )
+    add_common_cli_arguments(parser=parser)
+    args: argparse.Namespace = parser.parse_args()
+    return parse_common_cli_arguments(args=args)
+
+
+if __name__ == "__main__":
+    common_options: CommonWrapperOptions = _parse_cli_arguments()
+    result: int = main(
+        console_log_level=common_options.console_log_level,
+        include_data_types=common_options.data_types,
+        locations_to_include=common_options.locations_to_include,
+        working_directory=common_options.working_directory,
+    )
+    print_wrapper_banner(
+        wrapper_file=Path(__file__),
+        wrapper_version=WRAPPER_VERSION,
+        leading_blank_line=True,
+    )
+    if not common_options.no_pause:
+        pause_console()
+    raise SystemExit(result)

gis_processing/__init__.py

@@ -0,0 +1 @@
+"""Maintained TUFLOW GIS-processing wrappers bundled with ryan-tools."""

gis_processing/apply_qgis_styles_to_results.py

@@ -0,0 +1,85 @@
+# ryan-scripts\TUFLOW-python\gis_processing\apply_qgis_styles_to_results.py
+"""Wrapper Script: TUFLOW Results Styling.
+
+This script acts as a mutable wrapper for `ryan_library.orchestrators.tuflow.tuflow_results_styling`.
+It applies QGIS styles (.qml) to TUFLOW results (rasters/vectors) found in the target directory.
+Users can define custom QML overrides in the `user_qml_overrides` dictionary within this file.
+"""
+
+from pathlib import Path
+
+WRAPPER_VERSION = "2026-10-16.1"
+
+CONSOLE_LOG_LEVEL = "INFO"
+WORKING_DIR: Path = Path(__file__).absolute().parent
+
+# User Overrides: Define your custom QML paths here
+user_qml_overrides: dict[str, str] = {
+    # "d_Max": "/path/to/custom/depth_for_legend_max2m.qml",
+    # "h_Max": "/path/to/custom/hmax.qml",
+    # Add other overrides as needed
+}
+
+import argparse
+
+from loguru import logger
+
+from ryan_library.functions.loguru_helpers import setup_logger
+from ryan_library.functions.wrapper_utils import (
+    CommonWrapperOptions,
+    add_execution_cli_arguments,
+    change_working_directory,
+    parse_common_cli_arguments,
+    pause_console,
+    print_wrapper_banner,
+)
+from ryan_library.orchestrators.tuflow.tuflow_results_styling import TUFLOWResultsStyler
+
+
+def main(*, console_log_level: str | None = None, working_directory: Path | None = None) -> int:
+    """Main entry point for the TUFLOW Results Styling script.
+
+    This function sets the working directory to the script's location (or CWD),
+    initializes the logger, and applies the configured styles using `TUFLOWResultsStyler`.
+    It handles basic error logging and keeps the console window open upon completion/error.
+    """
+    print_wrapper_banner(wrapper_file=Path(__file__), wrapper_version=WRAPPER_VERSION)
+    try:
+        with setup_logger(console_log_level=console_log_level or CONSOLE_LOG_LEVEL):
+            script_location: Path = working_directory or WORKING_DIR
+            if not change_working_directory(target_dir=script_location):
+                return 1
+
+            # The orchestrator locates packaged styles, with a source-checkout fallback.
+            styler = TUFLOWResultsStyler(user_qml_overrides=user_qml_overrides)
+            styler.apply_styles()
+
+            logger.info("Styles were sourced from: {}", styler.default_styles_path)
+            return 0
+
+    except Exception:
+        logger.exception("TUFLOW result styling failed.")
+        return 1
+
+
+def _parse_cli_arguments() -> CommonWrapperOptions:
+    """Parse common execution overrides for the styling wrapper."""
+    parser = argparse.ArgumentParser(description="Apply configured QGIS styles to TUFLOW result files.")
+    add_execution_cli_arguments(parser=parser)
+    return parse_common_cli_arguments(args=parser.parse_args())
+
+
+if __name__ == "__main__":
+    common_options: CommonWrapperOptions = _parse_cli_arguments()
+    result: int = main(
+        console_log_level=common_options.console_log_level,
+        working_directory=common_options.working_directory,
+    )
+    print_wrapper_banner(
+        wrapper_file=Path(__file__),
+        wrapper_version=WRAPPER_VERSION,
+        leading_blank_line=True,
+    )
+    if not common_options.no_pause:
+        pause_console()
+    raise SystemExit(result)