HydPy 6.2.dev1__cp313-cp313-win_amd64.whl

hydpy/exe/hyd.py

@@ -0,0 +1,277 @@
+#!/usr/bin/env python
+"""The script for executing HydPy workflows.
+
+.. _`Python Launcher for Windows`: \
+https://docs.python.org/3/using/windows.html#launcher
+
+.. _`here`: https://bitbucket.org/vinay.sajip/pylauncher/downloads
+
+This script is thought to be called from a command line.  After successfully
+installating HydPy, you caninvoke it from anywhere on your computer.  Test this by just
+typing `hyd.py` into your command line:
+
+>>> import subprocess
+>>> from hydpy import run_subprocess
+>>> result = run_subprocess("hyd.py")  # doctest: +ELLIPSIS
+Invoking hyd.py without arguments resulted in the following error:
+The first positional argument defining the function to be called is missing.
+<BLANKLINE>
+See the following stack traceback for debugging:
+...
+
+If this test example does not work on your machine, you should first make sure there is
+a `hyd.py` file in the `Scripts` folder of your Python distribution and that the
+environment variable `Path` is pointing to this folder.  Windows users should also make
+shure to install the `Python Launcher for Windows`_.  The Python standard distribution
+contains this launcher, but other distributions like Anaconda do not.  You can find a
+suitable installer `here`_.  As a stopgap, you could directly call Python and pass the
+complete path of the `hyd.py` file available in your *HydPy* site-packages folder as an
+argument:
+
+>>> import sys
+>>> from hydpy.exe import hyd
+>>> command = f"{sys.executable} {hyd.__file__}"
+>>> from hydpy import repr_
+>>> repr_(command)  # doctest: +ELLIPSIS
+'...python... .../hydpy/exe/hyd.py'
+>>> result = run_subprocess(command)  # doctest: +ELLIPSIS
+Invoking hyd.py without arguments resulted in the following error:
+The first positional argument defining the function to be called is missing.
+...
+
+You are free to redirect output to a log file:
+
+>>> from hydpy import TestIO
+>>> TestIO.clear()
+>>> with TestIO():
+...     result = run_subprocess("hyd.py logfile=my_log_file.txt")
+>>> with TestIO(), open("my_log_file.txt") as logfile:
+...     print(logfile.read())  # doctest: +ELLIPSIS
+Invoking hyd.py with argument `logfile=my_log_file.txt` resulted in the following \
+error:
+The first positional argument defining the function to be called is missing.
+...
+
+When passing `default` as keyword argument `logfile`, function |prepare_logfile|
+generates a default name containing the current date and time:
+
+>>> with TestIO():
+...     result = run_subprocess("hyd.py logfile=default")
+>>> import os
+>>> with TestIO():
+...     for filename in os.listdir("."):
+...         if filename.endswith(".log"):
+...             print(filename)  # doctest: +ELLIPSIS
+hydpy_...-...-..._...-...-....log
+
+Without any further arguments, `hyd.py` does not know which function to call:
+
+>>> result = run_subprocess("hyd.py")  # doctest: +ELLIPSIS
+Invoking hyd.py without arguments resulted in the following error:
+The first positional argument defining the function to be called is missing.
+...
+
+The first additional argument must be an available "script function":
+
+>>> result = run_subprocess("hyd.py "
+...                         "wrong_argument")  # doctest: +ELLIPSIS
+Invoking hyd.py with argument `wrong_argument` resulted in the following error:
+There is no `wrong_argument` function callable by `hyd.py`.  Choose one of the \
+following instead: await_server, exec_commands, exec_script, run_doctests, \
+run_simulation, start_server, start_shell, xml_replace, and xml_validate.
+...
+
+Further argument requirements depend on the selected "script function":
+
+>>> result = run_subprocess("hyd.py "
+...                         "exec_commands")  # doctest: +ELLIPSIS
+Invoking hyd.py with argument `exec_commands` resulted in the following error:
+Function `exec_commands` requires `1` positional arguments (commands), but `0` are \
+given.
+...
+>>> result = run_subprocess("hyd.py "
+...                         "exec_commands "
+...                         "first_name "
+...                         "second_name")  # doctest: +ELLIPSIS
+Invoking hyd.py with arguments `exec_commands, first_name, second_name` resulted in \
+the following error:
+Function `exec_commands` allows `1` positional arguments (commands), but `2` are \
+given (first_name and second_name).
+...
+
+Optional keyword arguments are supported: (on Linux, we have to escape the characters \
+"(", ")", ";", and "'" in the following)
+
+>>> import platform
+>>> esc = "" if "windows" in platform.platform().lower() else "\\\\"
+>>> result = run_subprocess("hyd.py "
+...                         "exec_commands "
+...                         f"print{esc}(x+y{esc}) "
+...                         f"x={esc}'2{esc}' "
+...                         f"y={esc}'=1+1{esc}'")
+Start to execute the commands ['print(x+y)'] for testing purposes.
+2=1+1
+
+Error messages raised by the "script function" itself also find their way into the
+console or log file:
+
+>>> result = run_subprocess(  # doctest: +ELLIPSIS
+...    "hyd.py exec_commands "
+...    f"raise_RuntimeError{esc}({esc}'it_fails{esc}'{esc})")
+Start to execute the commands ["raise_RuntimeError('it_fails')"] for testing purposes.
+Invoking hyd.py with arguments `exec_commands, raise_RuntimeError('it_fails')` \
+resulted in the following error:
+it fails
+...
+
+The same is true for warning messages:
+
+>>> result = run_subprocess("hyd.py "  # doctest: +ELLIPSIS
+...                         "exec_commands "
+...                         f"import_warnings{esc};"
+...                         f"warnings.warn{esc}({esc}'it_stumbles{esc}'{esc})")
+Start to execute the commands ['import_warnings', "warnings.warn('it_stumbles')"] for \
+testing purposes...
+...UserWarning: it stumbles
+
+And the same is true for printed messages:
+
+>>> result = run_subprocess("hyd.py "
+...                         "exec_commands "
+...                         f"print{esc}({esc}'it_works{esc}'{esc})")
+Start to execute the commands ["print('it_works')"] for testing purposes.
+it works
+
+To report the importance level of individual log messages, use the optional `logstyle`
+keyword argument:
+
+>>> result = run_subprocess(   # doctest: +ELLIPSIS
+...     "hyd.py exec_commands "
+...     f"print{esc}({esc}'it_works{esc}'{esc}){esc};"
+...     f"import_warnings{esc};"
+...     f"warnings.warn{esc}({esc}'it_stumbles{esc}'{esc}){esc};"
+...     f"raise_RuntimeError{esc}({esc}'it_fails{esc}'{esc}) "
+...     "logstyle=prefixed")
+info: Start to execute the commands ["print('it_works')", 'import_warnings', \
+"warnings.warn('it_stumbles')", "raise_RuntimeError('it_fails')"] for testing purposes.
+info: it works
+warning: ...UserWarning: it stumbles
+error: Invoking hyd.py with arguments `exec_commands, print('it_works');\
+import_warnings;warnings.warn('it_stumbles');raise_RuntimeError('it_fails'), \
+logstyle=prefixed` resulted in the following error:
+error: it fails
+...
+
+So far, only `prefixed` and the default style `plain` have been implemented:
+
+>>> result = run_subprocess("hyd.py "  # doctest: +ELLIPSIS
+...                         "exec_commands "
+...                         "None "
+...                         "logstyle=missing")
+Invoking hyd.py with arguments `exec_commands, None, logstyle=missing` resulted in \
+the following error:
+The given log file style missing is not available.  Please choose one of the \
+following: plain and prefixed.
+...
+
+A related option is `errorstyle`, which allows for modifying the print style of
+exception messages.  So far, three error message printing styles are available:
+
+>>> result = run_subprocess("hyd.py exec_commands "  # doctest: +ELLIPSIS
+...                         "errorstyle=wrong")
+Invoking hyd.py with arguments `exec_commands, errorstyle=wrong` resulted in the \
+following error:
+The given error message style `wrong` is not available.  Please choose one of the \
+following: `multiline`, `single_line`, and `splittable`.
+...
+
+The (so far used) default is `multiline`.  It prints the context, the message, and the
+individual traceback components of the occurred error in separate lines:
+
+>>> result = run_subprocess(  # doctest: +ELLIPSIS
+...    "hyd.py exec_commands "
+...    "errorstyle=multiline "
+...    f"raise_RuntimeError{esc}({esc}'it_fails{esc}'{esc})")
+Start to execute the commands ["raise_RuntimeError('it_fails')"] for testing purposes.
+Invoking hyd.py with arguments `exec_commands, errorstyle=multiline, \
+raise_RuntimeError('it_fails')` resulted in the following error:
+it fails
+<BLANKLINE>
+See the following stack traceback for debugging:
+...
+
+.. _`Delft-FEWS`: https://oss.deltares.nl/web/delft-fews
+
+`multiline` provides exhaustive information in a human-readable form.  However,
+printing separate lines can confuse other tools that parse and forward HydPy's error
+messages (for example, `Delft-FEWS`_).  Hence, the first alternative, `single_line`,
+prints a single line.  It does so also in a readable form by omitting the traceback:
+
+>>> result = run_subprocess(  # doctest: +ELLIPSIS
+...    "hyd.py exec_commands "
+...    "errorstyle=single_line "
+...    f"raise_RuntimeError{esc}({esc}'it_fails{esc}'{esc})")
+Start to execute the commands ["raise_RuntimeError('it_fails')"] for testing purposes.
+Invoking hyd.py with arguments `exec_commands, errorstyle=single_line, \
+raise_RuntimeError('it_fails')` resulted in the following error: it fails
+
+The second alternative, `splittable`, squeezes the whole information (including the
+traceback) into a single line that uses the string `__hydpy_newline__` as a surrogate
+newline character, and so allows to convert the complete error message into the
+multiline form later:
+
+>>> result = run_subprocess(  # doctest: +ELLIPSIS
+...    "hyd.py exec_commands "
+...    "errorstyle=splittable "
+...    f"raise_RuntimeError{esc}({esc}'it_fails{esc}'{esc})")
+Start to execute the commands ["raise_RuntimeError('it_fails')"] for testing purposes.
+Invoking hyd.py with arguments `exec_commands, errorstyle=splittable, \
+raise_RuntimeError('it_fails')` resulted in the following error:__hydpy_newline__it \
+fails__hydpy_newline____hydpy_newline__See the following stack traceback for \
+debugging:__hydpy_newline__ ...__hydpy_newline__
+
+See the documentation on module |xmltools| for an actually successful example using the
+"script function" |run_simulation|.
+"""
+# import...
+# ...from standard-library
+import sys
+
+# ...from hydpy
+from hydpy.exe import commandtools
+
+
+def execute() -> None:
+    """Call |execute_scriptfunction| of module |commandtools| in case |hyd| is the main
+    script.
+
+    >>> from hydpy.exe import hyd
+    >>> from unittest import mock
+    >>> with (
+    ...     mock.patch("hydpy.exe.commandtools.execute_scriptfunction") as fun,
+    ...     mock.patch("sys.exit") as exit_,
+    ...     mock.patch.object(hyd, "__name__", "__not_main__"),
+    ... ):
+    ...     hyd.execute()
+    ...     exit_.called
+    False
+    >>> for return_value in (None, 0, 2):
+    ...     with (
+    ...         mock.patch(
+    ...             "hydpy.exe.commandtools.execute_scriptfunction",
+    ...              return_value=return_value
+    ...         ),
+    ...         mock.patch("sys.exit") as exit_,
+    ...         mock.patch.object(hyd, "__name__", "__main__"),
+    ... ):
+    ...         hyd.execute()
+    ...         exit_.call_args
+    call(False)
+    call(False)
+    call(True)
+    """
+    if __name__ == "__main__":
+        sys.exit(bool(commandtools.execute_scriptfunction()))
+
+
+execute()

hydpy/exe/modelimports.py

@@ -0,0 +1,41 @@
+"""This module bundles imports generally required for implementing new models.
+
+Module |modelimports| is supposed to shorten the import section
+of base and application models implemented.  Just write:
+
+>>> from hydpy.exe.modelimports import *
+
+Thereafter, the following objects are available:
+ * module |numpy|
+ * numpys |numpy.nan| and |numpy.inf|
+ * functions |parameterstep|, |simulationstep|, and |controlcheck|
+   of module |importtools|
+ * class |Tester| of module |testtools|
+ * class |Cythonizer| of module |modelutils|
+
+"""
+
+# import...
+# ...from site-packages
+import numpy
+from numpy import nan
+from numpy import inf
+
+# ...from HydPy
+# Load the required `magic` functions into the local namespace.
+from hydpy.core.importtools import parameterstep
+from hydpy.core.importtools import simulationstep
+from hydpy.core.importtools import controlcheck
+from hydpy.core.testtools import Tester
+from hydpy.cythons.modelutils import Cythonizer
+
+__all__ = [
+    "numpy",
+    "nan",
+    "inf",
+    "parameterstep",
+    "simulationstep",
+    "controlcheck",
+    "Tester",
+    "Cythonizer",
+]

hydpy/exe/replacetools.py

@@ -0,0 +1,216 @@
+"""This module implements tools for file related string substitutions."""
+
+# import...
+# ...from HydPy
+from hydpy import config
+from hydpy.core import objecttools
+from hydpy.core.typingtools import *
+
+
+def xml_replace(filename: str, *, printflag: bool = True, **replacements: str) -> None:
+    """Read the content of an XML template file (XMLT), apply the given
+    `replacements` to its substitution  markers, and write the result into
+    an XML file with the same name but ending with `xml` instead of `xmlt`.
+
+    First, we write an XMLT file, containing a regular HTML comment, a
+    readily defined element `e1`, and some other elements with
+    substitutions markers.  Substitution markers are HTML comments
+    starting and ending with the `|` character:
+
+    >>> from hydpy import xml_replace, TestIO
+    >>> with TestIO():
+    ...     with open("test1.xmlt", "w") as templatefile:
+    ...         _ = templatefile.write(
+    ...             "<!--a normal comment-->\\n"
+    ...             "<e1>element 1</e1>\\n"
+    ...             "<e2><!--|e2|--></e2>\\n"
+    ...             "<e3><!--|e3_|--></e3>\\n"
+    ...             "<e4><!--|e4=element 4|--></e4>\\n"
+    ...             "<e2><!--|e2|--></e2>")
+
+    Function |xml_replace| can both be called within a Python session and
+    from a command line.  We start with the first type of application.
+
+    Each substitution marker must be met by a keyword argument unless
+    it holds a default value (`e4`).  All arguments are converted to
+    a |str| object (`e3`).  Template files can use the same substitution
+    marker multiple times (`e2`):
+
+    >>> with TestIO():
+    ...     xml_replace("test1", e2="E2", e3_=3, e4="ELEMENT 4")
+    template file: test1.xmlt
+    target file: test1.xml
+    replacements:
+      e2 --> E2 (given argument)
+      e3_ --> 3 (given argument)
+      e4 --> ELEMENT 4 (given argument)
+      e2 --> E2 (given argument)
+    >>> with TestIO():
+    ...     with open("test1.xml") as targetfile:
+    ...         print(targetfile.read())
+    <!--a normal comment-->
+    <e1>element 1</e1>
+    <e2>E2</e2>
+    <e3>3</e3>
+    <e4>ELEMENT 4</e4>
+    <e2>E2</e2>
+
+    Without custom values, |xml_replace| applies predefined default
+    values, if available (`e4`):
+
+    >>> with TestIO():
+    ...     xml_replace("test1", e2="E2", e3_=3)    # doctest: +ELLIPSIS
+    template file: test1.xmlt
+    target file: test1.xml
+    replacements:
+      e2 --> E2 (given argument)
+      e3_ --> 3 (given argument)
+      e4 --> element 4 (default argument)
+      e2 --> E2 (given argument)
+    >>> with TestIO():
+    ...     with open("test1.xml") as targetfile:
+    ...         print(targetfile.read())
+    <!--a normal comment-->
+    <e1>element 1</e1>
+    <e2>E2</e2>
+    <e3>3</e3>
+    <e4>element 4</e4>
+    <e2>E2</e2>
+
+    Missing and useless keyword arguments result in errors:
+
+    >>> with TestIO():
+    ...     xml_replace("test1", e2="E2")
+    Traceback (most recent call last):
+    ...
+    RuntimeError: While trying to replace the markers `e2, e3_, and e4` \
+of the XML template file `test1.xmlt` with the available keywords `e2`, \
+the following error occurred: Marker `e3_` cannot be replaced.
+
+    >>> with TestIO():
+    ...     xml_replace("test1", e2="e2", e3_="E3", e4="e4", e5="e5")
+    Traceback (most recent call last):
+    ...
+    RuntimeError: While trying to replace the markers `e2, e3_, and e4` \
+of the XML template file `test1.xmlt` with the available keywords `e2, e3_, \
+e4, and e5`, the following error occurred: Keyword(s) `e5` cannot be used.
+
+    Using different default values for the same substitution marker
+    is not allowed:
+
+    >>> from hydpy import pub, TestIO, xml_replace
+    >>> with TestIO():
+    ...     with open("test2.xmlt", "w") as templatefile:
+    ...         _ = templatefile.write(
+    ...             "<e4><!--|e4=element 4|--></e4>\\n"
+    ...             "<e4><!--|e4=ELEMENT 4|--></e4>")
+
+    >>> with TestIO():
+    ...     xml_replace("test2", e4=4)
+    template file: test2.xmlt
+    target file: test2.xml
+    replacements:
+      e4 --> 4 (given argument)
+      e4 --> 4 (given argument)
+
+    >>> with TestIO():
+    ...     with open("test2.xml") as targetfile:
+    ...         print(targetfile.read())
+    <e4>4</e4>
+    <e4>4</e4>
+
+    >>> with TestIO():
+    ...     xml_replace("test2")
+    Traceback (most recent call last):
+    ...
+    RuntimeError: Template file `test2.xmlt` defines different default values \
+for marker `e4`.
+
+    As mentioned above, function |xml_replace| is registered as a "script
+    function" and can thus be used via command line:
+
+    >>> pub.scriptfunctions["xml_replace"].__name__
+    'xml_replace'
+    >>> pub.scriptfunctions["xml_replace"].__module__
+    'hydpy.exe.replacetools'
+
+    Use script |hyd| to execute function |xml_replace|:
+
+    >>> from hydpy import run_subprocess
+    >>> with TestIO():
+    ...     result = run_subprocess(
+    ...         'hyd.py xml_replace test1 e2="Element 2" e3_=3')
+    template file: test1.xmlt
+    target file: test1.xml
+    replacements:
+      e2 --> Element 2 (given argument)
+      e3_ --> 3 (given argument)
+      e4 --> element 4 (default argument)
+      e2 --> Element 2 (given argument)
+
+    >>> with TestIO():
+    ...     with open("test1.xml") as targetfile:
+    ...         print(targetfile.read())
+    <!--a normal comment-->
+    <e1>element 1</e1>
+    <e2>Element 2</e2>
+    <e3>3</e3>
+    <e4>element 4</e4>
+    <e2>Element 2</e2>
+    """
+    keywords = set(replacements.keys())
+    templatename = f"{filename}.xmlt"
+    targetname = f"{filename}.xml"
+    if printflag:
+        print(f"template file: {templatename}")
+        print(f"target file: {targetname}")
+        print("replacements:")
+    with open(templatename, encoding=config.ENCODING) as templatefile:
+        templatebody = templatefile.read()
+    parts = templatebody.replace("<!--|", "|-->").split("|-->")
+    defaults: dict[str, str] = {}
+    for idx, part in enumerate(parts):
+        if idx % 2:
+            subparts = part.partition("=")
+            if subparts[2]:
+                parts[idx] = subparts[0]
+                if subparts[0] not in replacements:
+                    if (subparts[0] in defaults) and (
+                        defaults[subparts[0]] != str(subparts[2])
+                    ):
+                        raise RuntimeError(
+                            f"Template file `{templatename}` defines different "
+                            f"default values for marker `{subparts[0]}`."
+                        )
+                    defaults[subparts[0]] = str(subparts[2])
+    markers = parts[1::2]
+    try:
+        unused_keywords = keywords.copy()
+        for idx, part in enumerate(parts):
+            if idx % 2:
+                argument_info = "given argument"
+                newpart = replacements.get(part)
+                if newpart is None:
+                    argument_info = "default argument"
+                    newpart = defaults.get(part)
+                if newpart is None:
+                    raise RuntimeError(f"Marker `{part}` cannot be replaced.")
+                if printflag:
+                    print(f"  {part} --> {newpart} ({argument_info})")
+                parts[idx] = str(newpart)
+                unused_keywords.discard(part)
+        targetbody = "".join(parts)
+        if unused_keywords:
+            raise RuntimeError(
+                f"Keyword(s) `{objecttools.enumeration(unused_keywords)}` "
+                f"cannot be used."
+            )
+        with open(targetname, "w", encoding=config.ENCODING) as targetfile:
+            targetfile.write(targetbody)
+    except BaseException:
+        objecttools.augment_excmessage(
+            f"While trying to replace the markers "
+            f"`{objecttools.enumeration(sorted(set(markers)))}` of the "
+            f"XML template file `{templatename}` with the available "
+            f"keywords `{objecttools.enumeration(sorted(keywords))}`"
+        )