hydrodl2 1.3.0__py3-none-any.whl

hydrodl2/__init__.py

@@ -0,0 +1,122 @@
+# src/hydrodl2/__init__.py
+import logging
+import os
+import sys
+from datetime import datetime
+from importlib.resources import files
+from pathlib import Path
+
+from platformdirs import user_config_dir
+
+from hydrodl2._version import __version__
+from hydrodl2.api import available_models, available_modules, load_model, load_module
+
+log = logging.getLogger('hydrodl2')
+
+# In case setuptools scm says version is 0.0.0
+assert not __version__.startswith('0.0.0')
+
+__all__ = [
+    '__version__',
+    'available_models',
+    'available_modules',
+    'load_model',
+    'load_module',
+]
+
+
+def _check_license_agreement():
+    """Checks if user has agreed to package license and prompts if not."""
+    package_name = 'hydrodl2'
+
+    config_dir = Path(user_config_dir(package_name))
+    agreement_file = config_dir / '.license_status'
+
+    model_classes = available_models()
+
+    if not agreement_file.exists():
+        print(f"\n[----- {package_name} LICENSE AGREEMENT -----]")
+
+        try:
+            # Find and read LICENSE file
+            license_path = files(package_name).parent.parent.joinpath("LICENSE")
+            license = license_path.read_text(encoding="utf-8")
+            print(license)
+        except FileNotFoundError:
+            # Fallback in case the LICENSE file wasn't packaged correctly
+            print(
+                "\n|> Error locating License. Showing summary <|\n"
+                "By using this software, you agree to the terms specified \n"
+                "in the Non-Commercial Software License Agreement: \n"
+                "\nhttps://github.com/mhpi/hydrodl2/blob/master/LICENSE \n"
+                "\n'hydrodl2' models are free for non-commercial use. \n"
+                "Prior authorization must be obtained for commercial \n"
+                "use. For further details, please contact the Pennsylvania \n"
+                "State University Office of Technology Management at \n"
+                "814.865.6277 or otminfo@psu.edu.\n"
+            )
+
+        print("\nThis agreement applies to all named models in this package:\n")
+
+        if model_classes:  # Avoid error if model_classes is empty
+            max_len = max(len(model) for model in model_classes) + 2
+        else:
+            max_len = 0
+
+        for model in model_classes:
+            model_string = ''
+            for submodel in model_classes[model]:
+                model_string += str(submodel) + ',  '
+            print(f"-> {model:<{max_len}}: {model_string[:-3]}")
+
+        print("-" * 40)
+
+        try:
+            response = input("Do you agree to these terms? Type 'Yes' to continue: ")
+        except EOFError:
+            # If we get here, it means we're in an environment that can't take
+            # input -- default to no agreement.
+            print("\n[!] No terminal detected. Skipping license prompt.")
+            return
+
+        if response.strip().lower() in ['yes', 'y']:
+            try:
+                config_dir.mkdir(parents=True, exist_ok=True)
+                agreement_file.write_text(
+                    f"accepted_on = {datetime.now().isoformat()}Z\nversion = 1\n",
+                    encoding="utf-8",
+                )
+                log.warning(
+                    f"License accepted. Agreement written to {agreement_file}\n"
+                )
+            except OSError as e:
+                log.warning(f"Failed to save agreement file {agreement_file}: {e}")
+                print(
+                    "You may need to run with administrator privileges to avoid "
+                    "repeating this process at runtime.",
+                )
+        else:
+            print("\n>| License agreement not accepted. Exiting. <|")
+            raise SystemExit(1)
+
+
+def _should_skip_license():
+    """Returns True if the license check should be bypassed."""
+    # 1. Check if we are in a Non-Interactive shell (No user to type 'Yes')
+    if not sys.stdin.isatty():
+        return True
+
+    # 2. Check for common 'Silent' or 'CI' flags
+    if os.environ.get('CI') or os.environ.get('NGEN_SILENT'):
+        return True
+
+    # 3. Check for the Docker flag (as a fallback)
+    if os.path.exists('/.dockerenv'):
+        return True
+
+    return False
+
+
+# This only runs once when package is first imported.
+if not _should_skip_license():
+    _check_license_agreement()

hydrodl2/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '1.3.0'
+__version_tuple__ = version_tuple = (1, 3, 0)
+
+__commit_id__ = commit_id = None

hydrodl2/api/__init__.py

@@ -0,0 +1,3 @@
+from .methods import available_models, available_modules, load_model, load_module
+
+__all__ = ['available_models', 'available_modules', 'load_model', 'load_module']

hydrodl2/api/methods.py

@@ -0,0 +1,144 @@
+"""
+Note: If adding new public methods, please add them to __all__
+at the top of the file and in api/__init__.py.
+"""
+
+import importlib.util
+import logging
+import os
+import re
+
+from torch.nn import Module
+
+from hydrodl2.core.utils import _get_dir, get_model_dirs, get_model_files
+
+log = logging.getLogger("hydrodl2")
+
+
+def available_models() -> dict[str, list[str]]:
+    """Identify and list all available models in hydroDL2.
+
+    Returns
+    -------
+    list
+        A list of available models.
+    """
+    # Path to the models directory
+    model_dir = _get_dir('models')
+    models = {}
+
+    dirs, _ = get_model_dirs(model_dir)
+    for dir in dirs:
+        _, file_names = get_model_files(dir)
+        models[dir.name] = file_names
+
+    return models
+
+
+def _list_available_models() -> list[str]:
+    """List all available models in hydroDL2 without the dict nesting
+    of available_models().
+
+    Returns
+    -------
+    list
+        A list of available models.
+    """
+    model_dir = _get_dir('models')
+    models = []
+    dirs, _ = get_model_dirs(model_dir)
+    for dir in dirs:
+        _, file_names = get_model_files(dir)
+        for file in file_names:
+            models.append(file)
+
+    return models
+
+
+def available_modules() -> dict[str, list[str]]:
+    """Identify and list all available modules in the hydroDL2.
+
+    Returns
+    -------
+    list
+        A list of available modules.
+    """
+    # Path to the modules directory
+    model_dir = _get_dir('modules')
+    modules = {}
+
+    dirs, _ = get_model_dirs(model_dir)
+    for dir in dirs:
+        _, file_names = get_model_files(dir)
+        modules[dir.name] = file_names
+
+    return modules
+
+
+def load_model(model: str, ver_name: str = None) -> Module:
+    """Load a model from the models directory.
+
+    Each model file in `models/` directory should only contain one model class.
+
+    Parameters
+    ----------
+    model
+        The model name.
+    ver_name
+        The version name (class) of the model to load within the model file.
+
+    Returns
+    -------
+    Module
+        The uninstantiated model.
+    """
+    parent_dir = _get_dir('models')
+
+    if ver_name is None:
+        ver_name = model  # Default to the model name if no version is specified
+
+    # Construct file path
+    model = re.sub(
+        r'([a-z])([A-Z])', r'\1_\2', model
+    ).lower()  # Convert camelCase to snake_case
+    model_dir = model.split('_')[
+        0
+    ].lower()  # Model class name is first word in snake_case
+    model_subpath = os.path.join(model_dir, f'{model}.py')
+
+    # Path to the module file in the model directory
+    source = os.path.join(parent_dir, model_subpath)
+
+    # Load the model dynamically as a module
+    try:
+        spec = importlib.util.spec_from_file_location(model, source)
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+    except ImportError as e:
+        raise ImportError(f"Model '{model}' not found.") from e
+
+    # Retrieve version name if possible, otherwise get first class in module
+    try:
+        cls = getattr(module, ver_name)
+    except AttributeError as e:
+        # Find first class in module (NOTE: not guaranteed accurate)
+        classes = [
+            attr
+            for attr in dir(module)
+            if isinstance(getattr(module, attr), type) and attr != 'Any'
+        ]
+        if not classes:
+            raise ImportError(f"Model version '{model}' not found.") from e
+
+        log.warning(
+            f"Model class '{ver_name}' not found in module '{module.__file__}'. "
+            f"Falling back to the first available: '{classes[0]}'."
+        )
+        cls = getattr(module, classes[0])
+
+    return cls
+
+
+def load_module():
+    """Load a module from the modules directory."""
+    raise NotImplementedError("This function is not yet implemented.")

hydrodl2/core/calc/__init__.py

@@ -0,0 +1,11 @@
+from .fdj import finite_difference_jacobian_p
+from .uh_routing import uh_conv, uh_gamma
+from .utils import change_param_range, param_bounds_2d
+
+__all__ = [
+    'change_param_range',
+    'param_bounds_2d',
+    'uh_gamma',
+    'uh_conv',
+    'finite_difference_jacobian_p',
+]