From 149658693f94c8897cb279d481a5ee7eedf965bc Mon Sep 17 00:00:00 2001 From: msweier Date: Mon, 2 Nov 2026 13:48:57 -0600 Subject: [PATCH 1/7] update python script launcher --- README.md | 10 +- jython_scripts/README.md | 168 +++- .../example_python_script_launcher.py | 774 ++++++++++++++++-- 3 files changed, 899 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index dba699c..900e404 100644 --- a/README.md +++ b/README.md @@ -66,9 +66,15 @@ pythonCWMS -m pip install package-name Packages included in releases are defined by [base requirements](requirements/base_requirements.txt) and [supplemental requirements](requirements/supplemental_requirements.txt), then resolved into the hash-pinned [Windows lock](requirements/locked.txt). -## RTS and HEC-DSS scripts +## RTS scripts -Jython is still used as a launcher inside RTS and HEC-DSS. Edit `python_script_path` and `args` in [example_python_script_launcher.py](jython_scripts/example_python_script_launcher.py). Set `args` to `None` or an empty string when no arguments are needed; multiple arguments are split before launching CPython. +Jython is still used inside RTS to launch external CPython processes. Configure +the `SCRIPTS` list in +[example_python_script_launcher.py](jython_scripts/example_python_script_launcher.py) +to provide a script menu, editable arguments, optional CDA credentials, and an optional snapshot of the active RTS forecast context. The launcher is +RTS-specific and does not run in HEC-DSSVue. + +See the [RTS launcher guide](jython_scripts/README.md#rts-cpython-launcher) for configuration, child-process environment variables, security considerations, and troubleshooting. Do not use the former Jython `install_python.py` workflow to install Python CWMS. The file remains as a compatibility notice for old bookmarks, while the signed Windows installer is documented in the [Jython migration guide](jython_scripts/README.md). Saved copies of the old installer are also stopped by the retirement document at the root of `main`. diff --git a/jython_scripts/README.md b/jython_scripts/README.md index c690b1a..d0a11af 100644 --- a/jython_scripts/README.md +++ b/jython_scripts/README.md @@ -33,7 +33,167 @@ Install-PythonCWMS.cmd -InstallRoot "D:\Tools\pythonCWMS" For an unattended replacement, use `Install-PythonCWMS.cmd -Force`. -The remaining Jython script in this directory is only a launcher for running -CPython scripts from RTS or HEC-DSSVue. See -[`example_python_script_launcher.py`](example_python_script_launcher.py) for -its configuration. +## RTS CPython launcher + +[`example_python_script_launcher.py`](example_python_script_launcher.py) is a +Jython 2.7 launcher for running external CPython scripts from RTS. It provides: + +- A menu of configured scripts with editable command-line arguments. +- Live, combined standard output and error output in a Swing window. +- Optional CDA endpoint, office, and OAuth credentials from the active RTS + connection. +- An optional snapshot of the active watershed, forecast, run, and forecast + time window. + +The launcher uses RTS-specific classes and is not compatible with HEC-DSSVue. +It runs one child process at a time. Closing the output window does not stop a +running child process. + +### Prerequisites + +1. Install Python CWMS using the instructions above. +2. Restart RTS after installation so it sees the new `PYTHON_CWMS_HOME` user + environment variable. +3. Confirm that `%PYTHON_CWMS_HOME%\python.exe` exists. +4. Log in to a CDA connection in RTS before running an entry configured with + `CDA_AUTH`. + +### Configure scripts + +Edit the `SCRIPTS` list near the top of the launcher. Each entry requires +`name`, `path`, and `args`. The `cda` and `rts_context` options default to +`CDA_NONE` and `False`. + +```python +SCRIPTS = [ + { + "name": "Local DSS Utility", + "path": r"C:\code\tools\local_dss_utility.py", + "args": r'--file "C:\data\forecast.dss"', + "cda": CDA_NONE, + "rts_context": True, + }, + { + "name": "Authenticated CDA Job", + "path": r"C:\code\jobs\store_data.py", + "args": "--dry-run", + "cda": CDA_AUTH, + "rts_context": False, + }, +] +``` + +Use an empty string for `args` when a script takes no arguments. The launcher +splits the argument text using Windows-style quoting and passes an argument +list directly to CPython without invoking a shell. The launch dialog lets the +operator edit arguments for that run without changing the configured default. + +Each child starts with its script directory as the working directory and uses +`%PYTHON_CWMS_HOME%\python.exe -u`. Standard error is merged into standard +output and streamed to the output window. + +### CDA access + +Choose the least-privileged CDA mode needed by each script: + +| Mode | Child environment | RTS requirement | +| --- | --- | --- | +| `CDA_NONE` | No CDA variables supplied by the launcher | None | +| `CDA_ENDPOINT` | `CDA_API_ROOT` and `OFFICE` | Active RTS CDA connection | +| `CDA_AUTH` | Endpoint and office plus `CDA_ACCESS_TOKEN`, `CDA_REFRESH_TOKEN`, `CDA_TOKEN_URL`, and `CDA_CLIENT_ID` | Authenticated OpenID RTS CDA connection | + +For `CDA_AUTH`, the launcher refreshes the cached RTS OAuth token immediately +before starting CPython. The CPython script is responsible for reading the +environment and initializing its CDA client. For example: + +```python +import os + +import cwms + +cwms.init_session( + api_root=os.environ["CDA_API_ROOT"], + token=os.environ.get("CDA_ACCESS_TOKEN"), +) + +office_id = os.environ["OFFICE"] +``` + +Before constructing a child environment, the launcher removes all CDA and RTS +variables that it manages. It then adds only the capabilities requested by the selected entry, preventing a `CDA_NONE` or `CDA_ENDPOINT` script from +accidentally inheriting credentials from RTS. + +`CDA_AUTH` gives the selected script and any processes it starts access to the current user's OAuth credentials. Configure only trusted scripts, and do not print tokens or a complete copy of the child environment. The launcher reports token lifetimes but does not display token values. + +### RTS context + +Set `rts_context` to `True` to provide `RTS_CONTEXT_JSON`, a versioned JSON +snapshot with this shape: + +```json +{ + "version": 1, + "watershed": { + "name": "Example Watershed", + "directory": "C:\\watersheds\\example", + "time_zone": "America/Chicago" + }, + "current_module": "Forecast", + "active_forecast": { + "name": "Example Forecast", + "directory": "C:\\watersheds\\example\\forecast\\example", + "dss_file": "C:\\watersheds\\example\\forecast\\example\\forecast.dss" + }, + "active_run": { + "name": "Run 1", + "key": "..." + }, + "time_window": { + "startTime": "2026-11-01T00:00:00-05:00", + "extractStartTime": "2026-11-01T06:00:00-06:00", + "forecastTime": "2026-11-02T06:00:00-06:00", + "endTime": "2026-11-05T06:00:00-06:00" + } +} +``` + +Unavailable values remain `null`. Forecast, run, and time-window values are +only populated when the current RTS module is a forecast tab. + +The same available values are also exported individually: + +| Context | Environment variables | +| --- | --- | +| Watershed | `RTS_WATERSHED_NAME`, `RTS_WATERSHED_DIRECTORY`, `RTS_WATERSHED_TIME_ZONE` | +| Module | `RTS_CURRENT_MODULE` | +| Forecast | `RTS_ACTIVE_FORECAST`, `RTS_ACTIVE_FORECAST_DIRECTORY`, `RTS_ACTIVE_FORECAST_DSS` | +| Run | `RTS_ACTIVE_RUN`, `RTS_ACTIVE_RUN_KEY` | +| Time window | `RTS_START_TIME`, `RTS_EXTRACT_START_TIME`, `RTS_FORECAST_TIME`, `RTS_END_TIME` | + +Times are ISO-8601 values with a UTC offset in the watershed time zone. A +CPython script can load the full snapshot with: + +```python +import json +import os + +context = json.loads(os.environ["RTS_CONTEXT_JSON"]) +``` + +### Troubleshooting + +- `PYTHON_CWMS_HOME environment variable is not set`: restart RTS after + installing Python CWMS, or verify the user environment variable. +- `Python executable not found`: verify that `PYTHON_CWMS_HOME` points to the + directory containing `python.exe`, normally + `C:\hec\python\pythonCWMS\python`. +- `This script requires an active RTS CDA connection`: select a CDA connection + in RTS or change the entry to `CDA_NONE`. +- Token or authentication errors: log out of CDA in RTS, log back in, and + launch the script again. +- `Python script not found`: correct the absolute `path` in the selected + `SCRIPTS` entry. + +The authenticated mode reads RTS's cached token provider through Java +reflection to avoid opening another interactive login. That implementation +detail may need updating when moving the launcher to a different RTS release. diff --git a/jython_scripts/example_python_script_launcher.py b/jython_scripts/example_python_script_launcher.py index 164a7b0..d93258f 100644 --- a/jython_scripts/example_python_script_launcher.py +++ b/jython_scripts/example_python_script_launcher.py @@ -1,67 +1,747 @@ +# RTS Jython 2.7 launcher for external CPython scripts. +# +# Requirements: +# 1. Set PYTHON_CWMS_HOME to the directory containing python.exe. +# 2. Scripts configured with cda=CDA_AUTH require an active RTS CDA login. + +import json import os import shlex import subprocess -# path to your python script -python_script_path = r"C:\code\CWMS-data-acquisition-python\src\get_USGS_measurements\get_USGS_measurements.py" +from com.auth0.jwt import JWT +from java.awt import BorderLayout, GridLayout +from java.awt.event import ActionListener +from java.lang import NoSuchFieldException, Runnable, System, Thread +from java.time import ZonedDateTime +from java.time.format import DateTimeFormatter +from javax.swing import ( + JComboBox, + JFrame, + JLabel, + JOptionPane, + JPanel, + JScrollPane, + JTextArea, + JTextField, + SwingUtilities, +) -# any arguments you may need, set to None or '' if not needed -args = "-d 60" +from hec.serversuite import ServerSuiteUtil +from hec2.rts.script import RTS +from hec2.rts.ui import ForecastTab +from mil.army.usace.hec.serversuite.cda import CdaAuthenticationSource -################################################################################################## -# 1. Get the expanded pythonCWMS directory from the environment variable -pythoncwms_home = os.environ.get('PYTHON_CWMS_HOME') # Get the value of PYTHON_CWMS_HOME -if not pythoncwms_home: - print("Error: PYTHON_CWMS_HOME environment variable not set.") - exit() # Or handle the error appropriately +# --------------------------------------------------------------------------- +# Configuration +# --------------------------------------------------------------------------- -# 2. Construct the pythonCWMS directory path using os.path.join +PYTHON_HOME_ENV = "PYTHON_CWMS_HOME" +RUNNING_PROPERTY = "rts.cpython.launcher.running" -pythoncwms_path = os.path.join(pythoncwms_home, "python.exe") # Path to the executable +CDA_NONE = "none" +CDA_ENDPOINT = "endpoint" +CDA_AUTH = "auth" -# 3. Check if the pythonCWMS_dir is in the PATH -current_path = os.environ.get('PATH', '') -if pythoncwms_home not in current_path: - os.environ['PATH'] = pythoncwms_home + os.pathsep + current_path - print("Updated PATH:", os.environ['PATH']) -else: - print("pythonCWMS directory already in PATH.") +# Environment variables controlled by this launcher. Clear them before +# configuring each child so scripts cannot inherit credentials accidentally. +MANAGED_ENVIRONMENT = ( + "CDA_API_ROOT", + "CDA_API_KEY", + "CDA_ACCESS_TOKEN", + "CDA_REFRESH_TOKEN", + "CDA_TOKEN_URL", + "CDA_CLIENT_ID", + "OFFICE", + "RTS_CONTEXT_JSON", + "RTS_WATERSHED_NAME", + "RTS_WATERSHED_DIRECTORY", + "RTS_WATERSHED_TIME_ZONE", + "RTS_CURRENT_MODULE", + "RTS_ACTIVE_FORECAST", + "RTS_ACTIVE_FORECAST_DIRECTORY", + "RTS_ACTIVE_FORECAST_DSS", + "RTS_ACTIVE_RUN", + "RTS_ACTIVE_RUN_KEY", + "RTS_START_TIME", + "RTS_EXTRACT_START_TIME", + "RTS_FORECAST_TIME", + "RTS_END_TIME", +) +# Per-script options: +# cda=CDA_NONE Do not pass CDA settings or credentials. +# cda=CDA_ENDPOINT Pass CDA_API_ROOT and OFFICE only. +# cda=CDA_AUTH Refresh, then pass RTS OAuth access/refresh credentials. +# rts_context=True Pass a snapshot of the current watershed/forecast/run. +SCRIPTS = [ + { + "name": "Get MN DNR Data", + "path": r"C:\code\mvp-wm-cwbi-jobs\python\get_mndnr.py", + "args": "-d 1", + "cda": CDA_AUTH, + "rts_context": False, + }, + { + "name": "Get MN DNR Data - Selected Locations", + "path": ( + r"C:\code\mvp-wm-cwbi-jobs\python\get_mndnr.py" + ), + "args": "-d 3 -l TMCM5 SPFM5", + "cda": CDA_AUTH, + "rts_context": False, + }, + { + "name": "Upload BLOB", + "path": ( + r"C:\code\CWMS-data-acquisition-python" + r"\src\upload_blob.py" + ), + "args": r'--file "C:\data\example.pdf"', + "cda": CDA_AUTH, + "rts_context": False, + }, +] -# 4. Test using os.system() -print("\n--- Testing pythonCWMS directly with os.system() ---") -return_code_os_system = os.system("pythonCWMS --version") -print("os.system return code:", return_code_os_system) +# Examples for additional entries: +# +# Local DSS script using the current watershed path, but no CDA variables: +# { +# "name": "Local DSS Utility", +# "path": r"C:\code\tools\local_dss_utility.py", +# "args": "", +# "cda": CDA_NONE, +# "rts_context": True, +# } +# +# Public/read-only CDA script that needs only the selected endpoint and office: +# { +# "name": "CDA Catalog", +# "path": r"C:\code\tools\cda_catalog.py", +# "args": "", +# "cda": CDA_ENDPOINT, +# "rts_context": False, +# } -if return_code_os_system == 0: - print("os.system succeeded. pythonCWMS is accessible.") -else: - print("os.system failed. pythonCWMS is NOT accessible. Check the PATH.") -# 5. Subprocess Call (only if the above test succeeds) -if return_code_os_system == 0: - python_executable = pythoncwms_path # Use the constructed path +# --------------------------------------------------------------------------- +# RTS authentication +# --------------------------------------------------------------------------- + +def get_private_field(obj, field_name): + """Read a private field from an object or one of its Java superclasses.""" + java_class = obj.getClass() + + while java_class is not None: + try: + field = java_class.getDeclaredField(field_name) + field.setAccessible(True) + return field.get(obj) + except NoSuchFieldException: + java_class = java_class.getSuperclass() + + raise RuntimeError( + "Field %s was not found on %s" + % (field_name, obj.getClass().getName()) + ) + + +def get_active_cda(): + """Return the active CDA source and data-access factory.""" + source = ServerSuiteUtil.getCwmsAuthenticationSource() + if not isinstance(source, CdaAuthenticationSource): + raise RuntimeError( + "This script requires an active RTS CDA connection" + ) + + factory = ServerSuiteUtil.getDataAccessFactory() + if factory is None: + raise RuntimeError( + "RTS does not have an active CDA DataAccessFactory" + ) + + return source, factory + + +def get_token_remaining_seconds(oauth_token): + """Return the access token's remaining lifetime.""" + access_token = oauth_token.getAccessToken() + if access_token is None or not str(access_token).strip(): + raise RuntimeError("The cached RTS access token is empty") + + expires_at = JWT.decode(str(access_token)).getExpiresAt() + if expires_at is None: + raise RuntimeError("The cached RTS access token has no expiration") + + remaining_millis = expires_at.getTime() - System.currentTimeMillis() + return max(0, int(remaining_millis / 1000)) + + +def refresh_token_before_launch(provider, oauth_token): + """Refresh through RTS immediately before launching CPython.""" + previous_remaining_seconds = get_token_remaining_seconds(oauth_token) + refresh_token = oauth_token.getRefreshToken() + if refresh_token is None or not str(refresh_token).strip(): + raise RuntimeError( + "The cached RTS OAuth token has no refresh token" + ) + + try: + oauth_token = provider.refreshToken() + except Exception as error: + raise RuntimeError( + "RTS could not refresh the CDA token. " + "Log out and back into CDA, then try again. %s" % error + ) + + if oauth_token is None: + raise RuntimeError("RTS returned no token after refresh") + + return ( + oauth_token, + get_token_remaining_seconds(oauth_token), + previous_remaining_seconds, + ) + + +def add_cda_environment(child_env, cda_mode): + """Add the requested level of CDA context to a child environment.""" + if cda_mode == CDA_NONE: + return None + + source, factory = get_active_cda() + child_env["CDA_API_ROOT"] = str(factory.getDataSourceUrl()) + child_env["OFFICE"] = str(factory.getOfficeId()) + + if cda_mode == CDA_ENDPOINT: + return None + + if cda_mode != CDA_AUTH: + raise RuntimeError("Unknown CDA mode: %s" % cda_mode) + + if not ServerSuiteUtil.isConnected(): + raise RuntimeError( + "This script requires an authenticated RTS CDA connection" + ) + + auth_optional = source.getCdaAuthExtension() + if not auth_optional.isPresent(): + raise RuntimeError( + "The active CDA connection has no authentication extension" + ) + + auth = auth_optional.get() + auth_type = str(auth.getExtensionType().name()) + if auth_type not in ("OPEN_ID", "OPEN_ID_CWBI"): + raise RuntimeError( + "RTS authentication type %s does not use an OAuth bearer token" + % auth_type + ) + + # Read the token created by the completed RTS login. Calling getToken() + # here could start another interactive OpenID login. + provider = get_private_field(auth, "_tokenProvider") + if provider is None: + raise RuntimeError( + "RTS has no cached token provider. " + "Log out and back into CDA, then try again." + ) + + oauth_token = get_private_field(provider, "token") + if oauth_token is None: + raise RuntimeError( + "RTS has no cached OAuth token. " + "Log out and back into CDA, then try again." + ) + + ( + oauth_token, + remaining_seconds, + previous_remaining_seconds, + ) = refresh_token_before_launch(provider, oauth_token) + access_token = oauth_token.getAccessToken() + refresh_token = oauth_token.getRefreshToken() + if access_token is None or not str(access_token).strip(): + raise RuntimeError("The cached RTS access token is empty") + if refresh_token is None or not str(refresh_token).strip(): + raise RuntimeError( + "The RTS OAuth response did not include a refresh token" + ) + + child_env["CDA_ACCESS_TOKEN"] = str(access_token) + child_env["CDA_REFRESH_TOKEN"] = str(refresh_token) + child_env["CDA_TOKEN_URL"] = str( + provider.getTokenUrl().getApiRoot() + ) + child_env["CDA_CLIENT_ID"] = str( + System.getProperty( + "hec.serversuite.cwbi.client.id.cda", + "cwms", + ) + ) + + return { + "lifetime_seconds": oauth_token.getExpiresIn(), + "remaining_seconds": remaining_seconds, + "previous_remaining_seconds": previous_remaining_seconds, + "refreshed": True, + } + + +def format_hec_time(hec_time, zone_id): + """Format a defined HecTime as an ISO-8601 timestamp with offset.""" + if hec_time is None or not hec_time.isDefined(): + return None + + instant = hec_time.getInstant(zone_id) + return str( + ZonedDateTime.ofInstant(instant, zone_id).format( + DateTimeFormatter.ISO_OFFSET_DATE_TIME + ) + ) + + +def add_rts_context_environment(child_env): + """Add a versioned snapshot of the current RTS context.""" + context = { + "version": 1, + "watershed": None, + "current_module": None, + "active_forecast": None, + "active_run": None, + "time_window": None, + } + + watershed = RTS.getWatershed() + zone_id = None + if watershed is not None: + time_zone = watershed.getTimeZone() + zone_id = time_zone.toZoneId() + watershed_context = { + "name": str(watershed.getName()), + "directory": str(watershed.getProjectDirectory()), + "time_zone": str(time_zone.getID()), + } + context["watershed"] = watershed_context + child_env["RTS_WATERSHED_NAME"] = watershed_context["name"] + child_env["RTS_WATERSHED_DIRECTORY"] = watershed_context["directory"] + child_env["RTS_WATERSHED_TIME_ZONE"] = watershed_context["time_zone"] + + current_module = RTS.getCurrentModule() + if current_module is not None: + module_name = str(current_module.getTabTitle()) + context["current_module"] = module_name + child_env["RTS_CURRENT_MODULE"] = module_name + + if isinstance(current_module, ForecastTab): + forecast = current_module.getForecast() + if forecast is not None: + forecast_context = { + "name": str(forecast.getName()), + "directory": str(forecast.getForecastDirectory()), + "dss_file": str(forecast.getForecastDSSFilename()), + } + context["active_forecast"] = forecast_context + child_env["RTS_ACTIVE_FORECAST"] = forecast_context["name"] + child_env["RTS_ACTIVE_FORECAST_DIRECTORY"] = ( + forecast_context["directory"] + ) + child_env["RTS_ACTIVE_FORECAST_DSS"] = forecast_context["dss_file"] + + forecast_run = current_module.getActiveForecastRun() + if forecast_run is not None: + run_context = { + "name": str(forecast_run.getName()), + "key": str(forecast_run.getKey()), + } + context["active_run"] = run_context + child_env["RTS_ACTIVE_RUN"] = run_context["name"] + child_env["RTS_ACTIVE_RUN_KEY"] = run_context["key"] + + # RTS calls the simulation start "lookback time" internally. + # The Forecast Time Window UI maps the four fields as follows. + run_time_window = ( + forecast_run.getRunTimeWindow() + if forecast_run is not None + else forecast.getRunTimeWindow() + ) + if run_time_window is not None and zone_id is not None: + time_window_context = { + "startTime": format_hec_time( + run_time_window.getLookbackTime(), + zone_id, + ), + "extractStartTime": format_hec_time( + run_time_window.getExtractStartTime(), + zone_id, + ), + "forecastTime": format_hec_time( + run_time_window.getStartTime(), + zone_id, + ), + "endTime": format_hec_time( + run_time_window.getEndTime(), + zone_id, + ), + } + context["time_window"] = time_window_context + + time_environment = ( + ("RTS_START_TIME", "startTime"), + ("RTS_EXTRACT_START_TIME", "extractStartTime"), + ("RTS_FORECAST_TIME", "forecastTime"), + ("RTS_END_TIME", "endTime"), + ) + for environment_name, context_name in time_environment: + value = time_window_context[context_name] + if value is not None: + child_env[environment_name] = value + + child_env["RTS_CONTEXT_JSON"] = json.dumps(context, sort_keys=True) + + +def build_child_environment(script): + """Build only the environment capabilities requested by a script.""" + child_env = os.environ.copy() + for name in MANAGED_ENVIRONMENT: + child_env.pop(name, None) + + cda_mode = script.get("cda", CDA_NONE) + token_info = add_cda_environment(child_env, cda_mode) + + if script.get("rts_context", False): + add_rts_context_environment(child_env) + + child_env["PYTHONUNBUFFERED"] = "1" + return child_env, token_info + + +# --------------------------------------------------------------------------- +# Command-line handling +# --------------------------------------------------------------------------- + +def split_arguments(argument_text): + """Split editable Windows-style arguments into a subprocess argument list.""" + if not argument_text or not argument_text.strip(): + return [] + + values = shlex.split(str(argument_text), posix=False) + result = [] + + # shlex with posix=False preserves surrounding quotes. Remove those + # quotes because Popen receives an argument list rather than a shell line. + for value in values: + if ( + len(value) >= 2 + and value[0] == value[-1] + and value[0] in ("'", '"') + ): + value = value[1:-1] + + result.append(value) + + return result + + +# --------------------------------------------------------------------------- +# Live output window +# --------------------------------------------------------------------------- + +class AppendOutput(Runnable): + def __init__(self, output_area, text): + self.output_area = output_area + self.text = text + + def run(self): + self.output_area.append(self.text) + document = self.output_area.getDocument() + self.output_area.setCaretPosition(document.getLength()) + + +def append_output(output_area, text): + """Append text safely from the process thread to the Swing UI.""" + SwingUtilities.invokeLater(AppendOutput(output_area, text)) + + +def create_output_window(script_name): + """Create and display a window for live subprocess output.""" + output_area = JTextArea(30, 110) + output_area.setEditable(False) + output_area.setLineWrap(False) + + frame = JFrame("Python Output: %s" % script_name) + frame.setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE) + frame.getContentPane().setLayout(BorderLayout()) + frame.getContentPane().add( + JScrollPane(output_area), + BorderLayout.CENTER, + ) + frame.pack() + frame.setLocationRelativeTo(None) + frame.setVisible(True) + + return output_area + + +# --------------------------------------------------------------------------- +# Background process +# --------------------------------------------------------------------------- + +class ChildProcessRunner(Runnable): + def __init__(self, selected_script, argument_text, output_area): + self.selected_script = selected_script + self.argument_text = argument_text + self.output_area = output_area + + def run(self): + process = None + + try: + python_home = os.environ.get(PYTHON_HOME_ENV) + if not python_home: + raise RuntimeError( + "%s environment variable is not set" + % PYTHON_HOME_ENV + ) + + python_executable = os.path.join( + python_home, + "python.exe", + ) + script_path = self.selected_script["path"] + + if not os.path.isfile(python_executable): + raise RuntimeError( + "Python executable not found: %s" + % python_executable + ) + + if not os.path.isfile(script_path): + raise RuntimeError( + "Python script not found: %s" % script_path + ) + + append_output( + self.output_area, + "Preparing requested runtime context...\n", + ) + + child_env, token_info = build_child_environment( + self.selected_script + ) + + child_env["PATH"] = ( + python_home + + os.pathsep + + child_env.get("PATH", "") + ) + + # -u makes stdin, stdout, and stderr unbuffered in CPython. + command = [python_executable, "-u", script_path] + command.extend(split_arguments(self.argument_text)) + + append_output( + self.output_area, + "\nStarting command:\n%s\n\n" + % subprocess.list2cmdline(command), + ) + append_output( + self.output_area, + "CDA context: %s\n" + % self.selected_script.get("cda", CDA_NONE), + ) + if "CDA_API_ROOT" in child_env: + append_output( + self.output_area, + "CDA_API_ROOT: %s\n" % child_env["CDA_API_ROOT"], + ) + append_output( + self.output_area, + "OFFICE: %s\n" % child_env["OFFICE"], + ) + if token_info is not None: + append_output( + self.output_area, + "Access-token lifetime: %s seconds\n" + % token_info["lifetime_seconds"], + ) + append_output( + self.output_area, + "Access token before refresh: %s seconds remaining\n" + % token_info["previous_remaining_seconds"], + ) + append_output( + self.output_area, + "Access token at launch: %s seconds remaining\n" + % token_info["remaining_seconds"], + ) + append_output( + self.output_area, + "Pre-launch token refresh: %s\n" + % ("yes" if token_info["refreshed"] else "not needed"), + ) + append_output( + self.output_area, + "RTS context snapshot: %s\n\n" + % ( + "enabled" + if self.selected_script.get("rts_context", False) + else "disabled" + ), + ) + + # Never print CDA_ACCESS_TOKEN or CDA_REFRESH_TOKEN. + process = subprocess.Popen( + command, + cwd=os.path.dirname(script_path), + env=child_env, + stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, + ) + + # Stream output instead of waiting for communicate() to return. + while True: + line = process.stdout.readline() + + if line: + try: + text = line.decode("utf-8", "replace") + except AttributeError: + text = str(line) + + append_output(self.output_area, text) + elif process.poll() is not None: + break + + return_code = process.wait() + + append_output( + self.output_area, + "\nProcess finished with return code %s.\n" + % return_code, + ) + + except Exception as error: + append_output( + self.output_area, + "\nLauncher error: %s\n" % error, + ) + + finally: + if process is not None and process.stdout is not None: + try: + process.stdout.close() + except Exception: + pass + + System.clearProperty(RUNNING_PROPERTY) + + +# --------------------------------------------------------------------------- +# Script-selection dialog +# --------------------------------------------------------------------------- + +def describe_script_context(script): + """Return a short description of a script's requested capabilities.""" + parts = ["CDA: %s" % script.get("cda", CDA_NONE)] + parts.append( + "RTS context: %s" + % ("yes" if script.get("rts_context", False) else "no") + ) + return " | ".join(parts) + + +class ScriptSelectionListener(ActionListener): + def __init__(self, selector, argument_field, context_field): + self.selector = selector + self.argument_field = argument_field + self.context_field = context_field + + def actionPerformed(self, event): + index = self.selector.getSelectedIndex() + script = SCRIPTS[index] + self.argument_field.setText(script["args"]) + self.context_field.setText(describe_script_context(script)) + + +def show_launcher(): + if not SCRIPTS: + JOptionPane.showMessageDialog( + None, + "No scripts are configured.", + "Python Launcher", + JOptionPane.ERROR_MESSAGE, + ) + return + + if System.getProperty(RUNNING_PROPERTY) == "true": + JOptionPane.showMessageDialog( + None, + "A Python job launched by this tool is already running.", + "Python Launcher", + JOptionPane.WARNING_MESSAGE, + ) + return + + selector = JComboBox() + for script in SCRIPTS: + selector.addItem(script["name"]) + + argument_field = JTextField(SCRIPTS[0]["args"], 70) + context_field = JTextField(describe_script_context(SCRIPTS[0]), 70) + context_field.setEditable(False) + selector.addActionListener( + ScriptSelectionListener(selector, argument_field, context_field) + ) + + panel = JPanel(GridLayout(0, 1, 5, 5)) + panel.add(JLabel("Python script:")) + panel.add(selector) + panel.add(JLabel("Injected context:")) + panel.add(context_field) + panel.add(JLabel("Arguments:")) + panel.add(argument_field) + + choice = JOptionPane.showConfirmDialog( + None, + panel, + "Run CPython Script", + JOptionPane.OK_CANCEL_OPTION, + JOptionPane.PLAIN_MESSAGE, + ) + + if choice != JOptionPane.OK_OPTION: + return + + selected_script = SCRIPTS[selector.getSelectedIndex()] + argument_text = str(argument_field.getText()) + + output_area = create_output_window( + selected_script["name"] + ) + + System.setProperty(RUNNING_PROPERTY, "true") - cmd = [python_executable, python_script_path] - if args: - cmd.extend(shlex.split(args)) + worker = Thread( + ChildProcessRunner( + selected_script, + argument_text, + output_area, + ), + "RTS-CPython-Launcher", + ) + worker.setDaemon(True) + worker.start() - print("Executing command:", cmd) - process = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE) - stdout, stderr = process.communicate() +class ShowLauncher(Runnable): + def run(self): + show_launcher() - stdout_str = stdout.decode('utf-8') - stderr_str = stderr.decode('utf-8') - stdout_str = stdout_str.replace('\r\n', '\n') - stderr_str = stderr_str.replace('\r\n', '\n') - print("STDOUT:\n") - print(stdout_str) - print("STDERR:\n") - print(stderr_str) - return_code = process.returncode - print("Return Code:", return_code) +# Swing dialogs and components should be created on the event-dispatch thread. +if SwingUtilities.isEventDispatchThread(): + show_launcher() else: - print("\nSkipping subprocess call because os.system failed.") + SwingUtilities.invokeAndWait(ShowLauncher()) From 3c499a200f31d1d146fccbc2f9facb009bc1fc2b Mon Sep 17 00:00:00 2001 From: msweier Date: Fri, 13 Nov 2026 13:52:49 -0600 Subject: [PATCH 2/7] add fpart variable --- jython_scripts/README.md | 20 +++++++++++ .../example_python_script_launcher.py | 33 +++++++++++++++++++ 2 files changed, 53 insertions(+) diff --git a/jython_scripts/README.md b/jython_scripts/README.md index d0a11af..bd6d294 100644 --- a/jython_scripts/README.md +++ b/jython_scripts/README.md @@ -148,6 +148,11 @@ snapshot with this shape: "name": "Run 1", "key": "..." }, + "selected_model_alternative": { + "name": "Forecast", + "program": "HEC-HMS", + "f_part": "C1" + }, "time_window": { "startTime": "2026-11-01T00:00:00-05:00", "extractStartTime": "2026-11-01T06:00:00-06:00", @@ -168,6 +173,7 @@ The same available values are also exported individually: | Module | `RTS_CURRENT_MODULE` | | Forecast | `RTS_ACTIVE_FORECAST`, `RTS_ACTIVE_FORECAST_DIRECTORY`, `RTS_ACTIVE_FORECAST_DSS` | | Run | `RTS_ACTIVE_RUN`, `RTS_ACTIVE_RUN_KEY` | +| Selected model alternative | `RTS_SELECTED_MODEL_ALTERNATIVE`, `RTS_SELECTED_MODEL_ALTERNATIVE_PROGRAM`, `RTS_SELECTED_MODEL_ALTERNATIVE_F_PART` | | Time window | `RTS_START_TIME`, `RTS_EXTRACT_START_TIME`, `RTS_FORECAST_TIME`, `RTS_END_TIME` | Times are ISO-8601 values with a UTC offset in the watershed time zone. A @@ -180,6 +186,20 @@ import os context = json.loads(os.environ["RTS_CONTEXT_JSON"]) ``` +When a model alternative is highlighted in the forecast tree, its DSS F-part +is available directly: + +```python +import os + +f_part = os.environ[ + "RTS_SELECTED_MODEL_ALTERNATIVE_F_PART" +] +``` + +The selected model alternative variables are omitted when the highlighted +forecast-tree node is not a model alternative. + ### Troubleshooting - `PYTHON_CWMS_HOME environment variable is not set`: restart RTS after diff --git a/jython_scripts/example_python_script_launcher.py b/jython_scripts/example_python_script_launcher.py index d93258f..9edce47 100644 --- a/jython_scripts/example_python_script_launcher.py +++ b/jython_scripts/example_python_script_launcher.py @@ -30,6 +30,7 @@ from hec.serversuite import ServerSuiteUtil from hec2.rts.script import RTS from hec2.rts.ui import ForecastTab +from hec2.rts.ui.tree import ModelAlternativeTreeNode from mil.army.usace.hec.serversuite.cda import CdaAuthenticationSource @@ -64,6 +65,9 @@ "RTS_ACTIVE_FORECAST_DSS", "RTS_ACTIVE_RUN", "RTS_ACTIVE_RUN_KEY", + "RTS_SELECTED_MODEL_ALTERNATIVE", + "RTS_SELECTED_MODEL_ALTERNATIVE_PROGRAM", + "RTS_SELECTED_MODEL_ALTERNATIVE_F_PART", "RTS_START_TIME", "RTS_EXTRACT_START_TIME", "RTS_FORECAST_TIME", @@ -310,6 +314,7 @@ def add_rts_context_environment(child_env): "current_module": None, "active_forecast": None, "active_run": None, + "selected_model_alternative": None, "time_window": None, } @@ -335,6 +340,34 @@ def add_rts_context_environment(child_env): child_env["RTS_CURRENT_MODULE"] = module_name if isinstance(current_module, ForecastTab): + selected_path = current_module.getSelectedTreePath() + selected_node = ( + selected_path.getLastPathComponent() + if selected_path is not None + else None + ) + if isinstance(selected_node, ModelAlternativeTreeNode): + model_alternative = selected_node.getModelAlternative() + f_part = model_alternative.getFpart() + model_alternative_context = { + "name": str(model_alternative.getName()), + "program": str(model_alternative.getProgram()), + "f_part": str(f_part) if f_part is not None else None, + } + context[ + "selected_model_alternative" + ] = model_alternative_context + child_env["RTS_SELECTED_MODEL_ALTERNATIVE"] = ( + model_alternative_context["name"] + ) + child_env["RTS_SELECTED_MODEL_ALTERNATIVE_PROGRAM"] = ( + model_alternative_context["program"] + ) + if model_alternative_context["f_part"] is not None: + child_env["RTS_SELECTED_MODEL_ALTERNATIVE_F_PART"] = ( + model_alternative_context["f_part"] + ) + forecast = current_module.getForecast() if forecast is not None: forecast_context = { From 8be4aef129aa1ef835ba79a81c65acffe6d88dc9 Mon Sep 17 00:00:00 2001 From: msweier Date: Mon, 16 Nov 2026 08:51:09 -0600 Subject: [PATCH 3/7] break out bridge script --- README.md | 5 +- jython_scripts/README.md | 83 +- .../example_direct_python_script_launcher.py | 44 + .../example_python_script_launcher.py | 657 +-------------- jython_scripts/rts_cpython_bridge.py | 767 ++++++++++++++++++ 5 files changed, 927 insertions(+), 629 deletions(-) create mode 100644 jython_scripts/example_direct_python_script_launcher.py create mode 100644 jython_scripts/rts_cpython_bridge.py diff --git a/README.md b/README.md index a4fcc33..36985d3 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,10 @@ Packages included in releases are defined by [base requirements](requirements/ba Jython is still used inside RTS to launch external CPython processes. Configure the `SCRIPTS` list in [example_python_script_launcher.py](jython_scripts/example_python_script_launcher.py) -to provide a script menu, editable arguments, optional CDA credentials, and an optional snapshot of the active RTS forecast context. The launcher is +to provide a script menu, or use +[example_direct_python_script_launcher.py](jython_scripts/example_direct_python_script_launcher.py) +for a one-click RTS button. Both entry points support optional CDA credentials +and an optional snapshot of the active RTS forecast context. The launcher is RTS-specific and does not run in HEC-DSSVue. See the [RTS launcher guide](jython_scripts/README.md#rts-cpython-launcher) for configuration, child-process environment variables, security considerations, and troubleshooting. diff --git a/jython_scripts/README.md b/jython_scripts/README.md index bd6d294..8bfc700 100644 --- a/jython_scripts/README.md +++ b/jython_scripts/README.md @@ -35,8 +35,19 @@ For an unattended replacement, use `Install-PythonCWMS.cmd -Force`. ## RTS CPython launcher -[`example_python_script_launcher.py`](example_python_script_launcher.py) is a -Jython 2.7 launcher for running external CPython scripts from RTS. It provides: +The RTS launcher is split into a reusable Jython 2.7 bridge and small entry +points: + +- [`rts_cpython_bridge.py`](rts_cpython_bridge.py) contains CDA + authentication, RTS context collection, CPython process execution, and the + live output window. +- [`example_python_script_launcher.py`](example_python_script_launcher.py) + provides the dropdown menu and editable arguments. +- [`example_direct_python_script_launcher.py`](example_direct_python_script_launcher.py) + launches one configured script immediately for use with an RTS script + button. + +Together they provide: - A menu of configured scripts with editable command-line arguments. - Live, combined standard output and error output in a Swing window. @@ -57,18 +68,30 @@ running child process. 3. Confirm that `%PYTHON_CWMS_HOME%\python.exe` exists. 4. Log in to a CDA connection in RTS before running an entry configured with `CDA_AUTH`. +5. Put `rts_cpython_bridge.py` in a stable directory. Set the + `RTS_CPYTHON_BRIDGE_HOME` user environment variable to that directory and + restart RTS, or edit `BRIDGE_DIRECTORY` near the top of each entry point. + +RTS evaluates button scripts as strings and does not automatically add the +entry-point file's directory to Jython's module search path. The entry points +therefore validate the configured bridge directory and add it to `sys.path` +before importing the bridge. Merely keeping the files beside each other is not +sufficient unless that directory is already on Jython's path. ### Configure scripts Edit the `SCRIPTS` list near the top of the launcher. Each entry requires -`name`, `path`, and `args`. The `cda` and `rts_context` options default to -`CDA_NONE` and `False`. +`name` and `path`. An absolute `path` can be used by itself. A relative `path` +requires an absolute `script_directory` from which it will be resolved. The +`args`, `cda`, and `rts_context` options default to an empty string, +`CDA_NONE`, and `False`. ```python SCRIPTS = [ { "name": "Local DSS Utility", - "path": r"C:\code\tools\local_dss_utility.py", + "path": "local_dss_utility.py", + "script_directory": r"C:\code\tools", "args": r'--file "C:\data\forecast.dss"', "cda": CDA_NONE, "rts_context": True, @@ -92,6 +115,47 @@ Each child starts with its script directory as the working directory and uses `%PYTHON_CWMS_HOME%\python.exe -u`. Standard error is merged into standard output and streamed to the output window. +### Configure a one-click button + +Copy and rename +[`example_direct_python_script_launcher.py`](example_direct_python_script_launcher.py) +for each dedicated RTS button. Edit its single `SCRIPT` dictionary using the +same fields shown above, then configure the RTS button to run that entry-point +file. + +```python +import os +import sys + +BRIDGE_DIRECTORY = os.environ.get( + "RTS_CPYTHON_BRIDGE_HOME", + r"C:\code\pythonCWMS\jython_scripts", +) +if BRIDGE_DIRECTORY not in sys.path: + sys.path.insert(0, BRIDGE_DIRECTORY) + +from rts_cpython_bridge import CDA_AUTH, launch_script + +SCRIPT_DIRECTORY = BRIDGE_DIRECTORY + +SCRIPT = { + "name": "Daily Regulation Sheet", + "path": os.path.join(SCRIPT_DIRECTORY, "daily_reg_sheet.py"), + "args": "report --open", + "cda": CDA_AUTH, + "rts_context": False, +} + +launch_script(SCRIPT) +``` + +Clicking the button bypasses the dropdown and argument editor. The live output +window still opens so progress and errors remain visible. The direct entry +point and dropdown use the same bridge, including the one-child-process limit +and CDA credential handling. When all files are together, leave +`SCRIPT_DIRECTORY` set to `BRIDGE_DIRECTORY`. Otherwise, set it to the +absolute directory containing the target CPython script. + ### CDA access Choose the least-privileged CDA mode needed by each script: @@ -119,6 +183,15 @@ cwms.init_session( office_id = os.environ["OFFICE"] ``` +If RTS reports that it is not connected to CDA, the launcher asks whether to +run the script anyway. Choosing **No** cancels the launch. Choosing **Yes** +bypasses the RTS connection-state check for that run. The launcher uses the +active CDA source and cached OAuth context when they are still available. If +CDA context preparation fails, it reports the reason in the output window and +starts the child without CDA environment variables. This is useful for scripts +that are configred to fall back to another data source +when CDA requests fail. + Before constructing a child environment, the launcher removes all CDA and RTS variables that it manages. It then adds only the capabilities requested by the selected entry, preventing a `CDA_NONE` or `CDA_ENDPOINT` script from accidentally inheriting credentials from RTS. diff --git a/jython_scripts/example_direct_python_script_launcher.py b/jython_scripts/example_direct_python_script_launcher.py new file mode 100644 index 0000000..34a1042 --- /dev/null +++ b/jython_scripts/example_direct_python_script_launcher.py @@ -0,0 +1,44 @@ +# RTS Jython 2.7 one-click entry point for one external CPython script. +# +# Set BRIDGE_DIRECTORY to the directory containing rts_cpython_bridge.py, then +# assign this file to an RTS script button. + +import os +import sys + + +BRIDGE_DIRECTORY_ENV = "RTS_CPYTHON_BRIDGE_HOME" +BRIDGE_DIRECTORY = os.environ.get( + BRIDGE_DIRECTORY_ENV, + r"C:\code\pythonCWMS\jython_scripts", +) +BRIDGE_PATH = os.path.join( + BRIDGE_DIRECTORY, + "rts_cpython_bridge.py", +) + +if not os.path.isfile(BRIDGE_PATH): + raise RuntimeError( + "RTS CPython bridge not found: %s. Set %s or edit " + "BRIDGE_DIRECTORY in this launcher." + % (BRIDGE_PATH, BRIDGE_DIRECTORY_ENV) + ) + +if BRIDGE_DIRECTORY not in sys.path: + sys.path.insert(0, BRIDGE_DIRECTORY) + +from rts_cpython_bridge import CDA_AUTH, launch_script + + +SCRIPT_DIRECTORY = os.path.dirname(os.path.abspath(__file__)) + +SCRIPT = { + "name": "Daily Regulation Sheet", + "path": os.path.join(SCRIPT_DIRECTORY, "daily_reg_sheet.py"), + "args": "report --open", + "cda": CDA_AUTH, + "rts_context": False, +} + + +launch_script(SCRIPT) diff --git a/jython_scripts/example_python_script_launcher.py b/jython_scripts/example_python_script_launcher.py index 9edce47..0e3611a 100644 --- a/jython_scripts/example_python_script_launcher.py +++ b/jython_scripts/example_python_script_launcher.py @@ -1,84 +1,58 @@ -# RTS Jython 2.7 launcher for external CPython scripts. +# RTS Jython 2.7 menu for launching configured external CPython scripts. # -# Requirements: -# 1. Set PYTHON_CWMS_HOME to the directory containing python.exe. -# 2. Scripts configured with cda=CDA_AUTH require an active RTS CDA login. +# Set BRIDGE_DIRECTORY to the directory containing rts_cpython_bridge.py. -import json import os -import shlex -import subprocess +import sys -from com.auth0.jwt import JWT -from java.awt import BorderLayout, GridLayout +from java.awt import GridLayout from java.awt.event import ActionListener -from java.lang import NoSuchFieldException, Runnable, System, Thread -from java.time import ZonedDateTime -from java.time.format import DateTimeFormatter +from java.lang import Runnable from javax.swing import ( JComboBox, - JFrame, JLabel, JOptionPane, JPanel, - JScrollPane, - JTextArea, JTextField, SwingUtilities, ) -from hec.serversuite import ServerSuiteUtil -from hec2.rts.script import RTS -from hec2.rts.ui import ForecastTab -from hec2.rts.ui.tree import ModelAlternativeTreeNode -from mil.army.usace.hec.serversuite.cda import CdaAuthenticationSource +BRIDGE_DIRECTORY_ENV = "RTS_CPYTHON_BRIDGE_HOME" +BRIDGE_DIRECTORY = os.environ.get( + BRIDGE_DIRECTORY_ENV, + r"C:\code\pythonCWMS\jython_scripts", +) +BRIDGE_PATH = os.path.join( + BRIDGE_DIRECTORY, + "rts_cpython_bridge.py", +) -# --------------------------------------------------------------------------- -# Configuration -# --------------------------------------------------------------------------- - -PYTHON_HOME_ENV = "PYTHON_CWMS_HOME" -RUNNING_PROPERTY = "rts.cpython.launcher.running" +if not os.path.isfile(BRIDGE_PATH): + raise RuntimeError( + "RTS CPython bridge not found: %s. Set %s or edit " + "BRIDGE_DIRECTORY in this launcher." + % (BRIDGE_PATH, BRIDGE_DIRECTORY_ENV) + ) -CDA_NONE = "none" -CDA_ENDPOINT = "endpoint" -CDA_AUTH = "auth" +if BRIDGE_DIRECTORY not in sys.path: + sys.path.insert(0, BRIDGE_DIRECTORY) -# Environment variables controlled by this launcher. Clear them before -# configuring each child so scripts cannot inherit credentials accidentally. -MANAGED_ENVIRONMENT = ( - "CDA_API_ROOT", - "CDA_API_KEY", - "CDA_ACCESS_TOKEN", - "CDA_REFRESH_TOKEN", - "CDA_TOKEN_URL", - "CDA_CLIENT_ID", - "OFFICE", - "RTS_CONTEXT_JSON", - "RTS_WATERSHED_NAME", - "RTS_WATERSHED_DIRECTORY", - "RTS_WATERSHED_TIME_ZONE", - "RTS_CURRENT_MODULE", - "RTS_ACTIVE_FORECAST", - "RTS_ACTIVE_FORECAST_DIRECTORY", - "RTS_ACTIVE_FORECAST_DSS", - "RTS_ACTIVE_RUN", - "RTS_ACTIVE_RUN_KEY", - "RTS_SELECTED_MODEL_ALTERNATIVE", - "RTS_SELECTED_MODEL_ALTERNATIVE_PROGRAM", - "RTS_SELECTED_MODEL_ALTERNATIVE_F_PART", - "RTS_START_TIME", - "RTS_EXTRACT_START_TIME", - "RTS_FORECAST_TIME", - "RTS_END_TIME", +from rts_cpython_bridge import ( + CDA_AUTH, + CDA_ENDPOINT, + CDA_NONE, + is_script_running, + launch_script, ) + # Per-script options: # cda=CDA_NONE Do not pass CDA settings or credentials. # cda=CDA_ENDPOINT Pass CDA_API_ROOT and OFFICE only. # cda=CDA_AUTH Refresh, then pass RTS OAuth access/refresh credentials. # rts_context=True Pass a snapshot of the current watershed/forecast/run. +# script_directory Absolute base directory for a relative path. SCRIPTS = [ { "name": "Get MN DNR Data", @@ -129,552 +103,6 @@ # } -# --------------------------------------------------------------------------- -# RTS authentication -# --------------------------------------------------------------------------- - -def get_private_field(obj, field_name): - """Read a private field from an object or one of its Java superclasses.""" - java_class = obj.getClass() - - while java_class is not None: - try: - field = java_class.getDeclaredField(field_name) - field.setAccessible(True) - return field.get(obj) - except NoSuchFieldException: - java_class = java_class.getSuperclass() - - raise RuntimeError( - "Field %s was not found on %s" - % (field_name, obj.getClass().getName()) - ) - - -def get_active_cda(): - """Return the active CDA source and data-access factory.""" - source = ServerSuiteUtil.getCwmsAuthenticationSource() - if not isinstance(source, CdaAuthenticationSource): - raise RuntimeError( - "This script requires an active RTS CDA connection" - ) - - factory = ServerSuiteUtil.getDataAccessFactory() - if factory is None: - raise RuntimeError( - "RTS does not have an active CDA DataAccessFactory" - ) - - return source, factory - - -def get_token_remaining_seconds(oauth_token): - """Return the access token's remaining lifetime.""" - access_token = oauth_token.getAccessToken() - if access_token is None or not str(access_token).strip(): - raise RuntimeError("The cached RTS access token is empty") - - expires_at = JWT.decode(str(access_token)).getExpiresAt() - if expires_at is None: - raise RuntimeError("The cached RTS access token has no expiration") - - remaining_millis = expires_at.getTime() - System.currentTimeMillis() - return max(0, int(remaining_millis / 1000)) - - -def refresh_token_before_launch(provider, oauth_token): - """Refresh through RTS immediately before launching CPython.""" - previous_remaining_seconds = get_token_remaining_seconds(oauth_token) - refresh_token = oauth_token.getRefreshToken() - if refresh_token is None or not str(refresh_token).strip(): - raise RuntimeError( - "The cached RTS OAuth token has no refresh token" - ) - - try: - oauth_token = provider.refreshToken() - except Exception as error: - raise RuntimeError( - "RTS could not refresh the CDA token. " - "Log out and back into CDA, then try again. %s" % error - ) - - if oauth_token is None: - raise RuntimeError("RTS returned no token after refresh") - - return ( - oauth_token, - get_token_remaining_seconds(oauth_token), - previous_remaining_seconds, - ) - - -def add_cda_environment(child_env, cda_mode): - """Add the requested level of CDA context to a child environment.""" - if cda_mode == CDA_NONE: - return None - - source, factory = get_active_cda() - child_env["CDA_API_ROOT"] = str(factory.getDataSourceUrl()) - child_env["OFFICE"] = str(factory.getOfficeId()) - - if cda_mode == CDA_ENDPOINT: - return None - - if cda_mode != CDA_AUTH: - raise RuntimeError("Unknown CDA mode: %s" % cda_mode) - - if not ServerSuiteUtil.isConnected(): - raise RuntimeError( - "This script requires an authenticated RTS CDA connection" - ) - - auth_optional = source.getCdaAuthExtension() - if not auth_optional.isPresent(): - raise RuntimeError( - "The active CDA connection has no authentication extension" - ) - - auth = auth_optional.get() - auth_type = str(auth.getExtensionType().name()) - if auth_type not in ("OPEN_ID", "OPEN_ID_CWBI"): - raise RuntimeError( - "RTS authentication type %s does not use an OAuth bearer token" - % auth_type - ) - - # Read the token created by the completed RTS login. Calling getToken() - # here could start another interactive OpenID login. - provider = get_private_field(auth, "_tokenProvider") - if provider is None: - raise RuntimeError( - "RTS has no cached token provider. " - "Log out and back into CDA, then try again." - ) - - oauth_token = get_private_field(provider, "token") - if oauth_token is None: - raise RuntimeError( - "RTS has no cached OAuth token. " - "Log out and back into CDA, then try again." - ) - - ( - oauth_token, - remaining_seconds, - previous_remaining_seconds, - ) = refresh_token_before_launch(provider, oauth_token) - access_token = oauth_token.getAccessToken() - refresh_token = oauth_token.getRefreshToken() - if access_token is None or not str(access_token).strip(): - raise RuntimeError("The cached RTS access token is empty") - if refresh_token is None or not str(refresh_token).strip(): - raise RuntimeError( - "The RTS OAuth response did not include a refresh token" - ) - - child_env["CDA_ACCESS_TOKEN"] = str(access_token) - child_env["CDA_REFRESH_TOKEN"] = str(refresh_token) - child_env["CDA_TOKEN_URL"] = str( - provider.getTokenUrl().getApiRoot() - ) - child_env["CDA_CLIENT_ID"] = str( - System.getProperty( - "hec.serversuite.cwbi.client.id.cda", - "cwms", - ) - ) - - return { - "lifetime_seconds": oauth_token.getExpiresIn(), - "remaining_seconds": remaining_seconds, - "previous_remaining_seconds": previous_remaining_seconds, - "refreshed": True, - } - - -def format_hec_time(hec_time, zone_id): - """Format a defined HecTime as an ISO-8601 timestamp with offset.""" - if hec_time is None or not hec_time.isDefined(): - return None - - instant = hec_time.getInstant(zone_id) - return str( - ZonedDateTime.ofInstant(instant, zone_id).format( - DateTimeFormatter.ISO_OFFSET_DATE_TIME - ) - ) - - -def add_rts_context_environment(child_env): - """Add a versioned snapshot of the current RTS context.""" - context = { - "version": 1, - "watershed": None, - "current_module": None, - "active_forecast": None, - "active_run": None, - "selected_model_alternative": None, - "time_window": None, - } - - watershed = RTS.getWatershed() - zone_id = None - if watershed is not None: - time_zone = watershed.getTimeZone() - zone_id = time_zone.toZoneId() - watershed_context = { - "name": str(watershed.getName()), - "directory": str(watershed.getProjectDirectory()), - "time_zone": str(time_zone.getID()), - } - context["watershed"] = watershed_context - child_env["RTS_WATERSHED_NAME"] = watershed_context["name"] - child_env["RTS_WATERSHED_DIRECTORY"] = watershed_context["directory"] - child_env["RTS_WATERSHED_TIME_ZONE"] = watershed_context["time_zone"] - - current_module = RTS.getCurrentModule() - if current_module is not None: - module_name = str(current_module.getTabTitle()) - context["current_module"] = module_name - child_env["RTS_CURRENT_MODULE"] = module_name - - if isinstance(current_module, ForecastTab): - selected_path = current_module.getSelectedTreePath() - selected_node = ( - selected_path.getLastPathComponent() - if selected_path is not None - else None - ) - if isinstance(selected_node, ModelAlternativeTreeNode): - model_alternative = selected_node.getModelAlternative() - f_part = model_alternative.getFpart() - model_alternative_context = { - "name": str(model_alternative.getName()), - "program": str(model_alternative.getProgram()), - "f_part": str(f_part) if f_part is not None else None, - } - context[ - "selected_model_alternative" - ] = model_alternative_context - child_env["RTS_SELECTED_MODEL_ALTERNATIVE"] = ( - model_alternative_context["name"] - ) - child_env["RTS_SELECTED_MODEL_ALTERNATIVE_PROGRAM"] = ( - model_alternative_context["program"] - ) - if model_alternative_context["f_part"] is not None: - child_env["RTS_SELECTED_MODEL_ALTERNATIVE_F_PART"] = ( - model_alternative_context["f_part"] - ) - - forecast = current_module.getForecast() - if forecast is not None: - forecast_context = { - "name": str(forecast.getName()), - "directory": str(forecast.getForecastDirectory()), - "dss_file": str(forecast.getForecastDSSFilename()), - } - context["active_forecast"] = forecast_context - child_env["RTS_ACTIVE_FORECAST"] = forecast_context["name"] - child_env["RTS_ACTIVE_FORECAST_DIRECTORY"] = ( - forecast_context["directory"] - ) - child_env["RTS_ACTIVE_FORECAST_DSS"] = forecast_context["dss_file"] - - forecast_run = current_module.getActiveForecastRun() - if forecast_run is not None: - run_context = { - "name": str(forecast_run.getName()), - "key": str(forecast_run.getKey()), - } - context["active_run"] = run_context - child_env["RTS_ACTIVE_RUN"] = run_context["name"] - child_env["RTS_ACTIVE_RUN_KEY"] = run_context["key"] - - # RTS calls the simulation start "lookback time" internally. - # The Forecast Time Window UI maps the four fields as follows. - run_time_window = ( - forecast_run.getRunTimeWindow() - if forecast_run is not None - else forecast.getRunTimeWindow() - ) - if run_time_window is not None and zone_id is not None: - time_window_context = { - "startTime": format_hec_time( - run_time_window.getLookbackTime(), - zone_id, - ), - "extractStartTime": format_hec_time( - run_time_window.getExtractStartTime(), - zone_id, - ), - "forecastTime": format_hec_time( - run_time_window.getStartTime(), - zone_id, - ), - "endTime": format_hec_time( - run_time_window.getEndTime(), - zone_id, - ), - } - context["time_window"] = time_window_context - - time_environment = ( - ("RTS_START_TIME", "startTime"), - ("RTS_EXTRACT_START_TIME", "extractStartTime"), - ("RTS_FORECAST_TIME", "forecastTime"), - ("RTS_END_TIME", "endTime"), - ) - for environment_name, context_name in time_environment: - value = time_window_context[context_name] - if value is not None: - child_env[environment_name] = value - - child_env["RTS_CONTEXT_JSON"] = json.dumps(context, sort_keys=True) - - -def build_child_environment(script): - """Build only the environment capabilities requested by a script.""" - child_env = os.environ.copy() - for name in MANAGED_ENVIRONMENT: - child_env.pop(name, None) - - cda_mode = script.get("cda", CDA_NONE) - token_info = add_cda_environment(child_env, cda_mode) - - if script.get("rts_context", False): - add_rts_context_environment(child_env) - - child_env["PYTHONUNBUFFERED"] = "1" - return child_env, token_info - - -# --------------------------------------------------------------------------- -# Command-line handling -# --------------------------------------------------------------------------- - -def split_arguments(argument_text): - """Split editable Windows-style arguments into a subprocess argument list.""" - if not argument_text or not argument_text.strip(): - return [] - - values = shlex.split(str(argument_text), posix=False) - result = [] - - # shlex with posix=False preserves surrounding quotes. Remove those - # quotes because Popen receives an argument list rather than a shell line. - for value in values: - if ( - len(value) >= 2 - and value[0] == value[-1] - and value[0] in ("'", '"') - ): - value = value[1:-1] - - result.append(value) - - return result - - -# --------------------------------------------------------------------------- -# Live output window -# --------------------------------------------------------------------------- - -class AppendOutput(Runnable): - def __init__(self, output_area, text): - self.output_area = output_area - self.text = text - - def run(self): - self.output_area.append(self.text) - document = self.output_area.getDocument() - self.output_area.setCaretPosition(document.getLength()) - - -def append_output(output_area, text): - """Append text safely from the process thread to the Swing UI.""" - SwingUtilities.invokeLater(AppendOutput(output_area, text)) - - -def create_output_window(script_name): - """Create and display a window for live subprocess output.""" - output_area = JTextArea(30, 110) - output_area.setEditable(False) - output_area.setLineWrap(False) - - frame = JFrame("Python Output: %s" % script_name) - frame.setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE) - frame.getContentPane().setLayout(BorderLayout()) - frame.getContentPane().add( - JScrollPane(output_area), - BorderLayout.CENTER, - ) - frame.pack() - frame.setLocationRelativeTo(None) - frame.setVisible(True) - - return output_area - - -# --------------------------------------------------------------------------- -# Background process -# --------------------------------------------------------------------------- - -class ChildProcessRunner(Runnable): - def __init__(self, selected_script, argument_text, output_area): - self.selected_script = selected_script - self.argument_text = argument_text - self.output_area = output_area - - def run(self): - process = None - - try: - python_home = os.environ.get(PYTHON_HOME_ENV) - if not python_home: - raise RuntimeError( - "%s environment variable is not set" - % PYTHON_HOME_ENV - ) - - python_executable = os.path.join( - python_home, - "python.exe", - ) - script_path = self.selected_script["path"] - - if not os.path.isfile(python_executable): - raise RuntimeError( - "Python executable not found: %s" - % python_executable - ) - - if not os.path.isfile(script_path): - raise RuntimeError( - "Python script not found: %s" % script_path - ) - - append_output( - self.output_area, - "Preparing requested runtime context...\n", - ) - - child_env, token_info = build_child_environment( - self.selected_script - ) - - child_env["PATH"] = ( - python_home - + os.pathsep - + child_env.get("PATH", "") - ) - - # -u makes stdin, stdout, and stderr unbuffered in CPython. - command = [python_executable, "-u", script_path] - command.extend(split_arguments(self.argument_text)) - - append_output( - self.output_area, - "\nStarting command:\n%s\n\n" - % subprocess.list2cmdline(command), - ) - append_output( - self.output_area, - "CDA context: %s\n" - % self.selected_script.get("cda", CDA_NONE), - ) - if "CDA_API_ROOT" in child_env: - append_output( - self.output_area, - "CDA_API_ROOT: %s\n" % child_env["CDA_API_ROOT"], - ) - append_output( - self.output_area, - "OFFICE: %s\n" % child_env["OFFICE"], - ) - if token_info is not None: - append_output( - self.output_area, - "Access-token lifetime: %s seconds\n" - % token_info["lifetime_seconds"], - ) - append_output( - self.output_area, - "Access token before refresh: %s seconds remaining\n" - % token_info["previous_remaining_seconds"], - ) - append_output( - self.output_area, - "Access token at launch: %s seconds remaining\n" - % token_info["remaining_seconds"], - ) - append_output( - self.output_area, - "Pre-launch token refresh: %s\n" - % ("yes" if token_info["refreshed"] else "not needed"), - ) - append_output( - self.output_area, - "RTS context snapshot: %s\n\n" - % ( - "enabled" - if self.selected_script.get("rts_context", False) - else "disabled" - ), - ) - - # Never print CDA_ACCESS_TOKEN or CDA_REFRESH_TOKEN. - process = subprocess.Popen( - command, - cwd=os.path.dirname(script_path), - env=child_env, - stdout=subprocess.PIPE, - stderr=subprocess.STDOUT, - ) - - # Stream output instead of waiting for communicate() to return. - while True: - line = process.stdout.readline() - - if line: - try: - text = line.decode("utf-8", "replace") - except AttributeError: - text = str(line) - - append_output(self.output_area, text) - elif process.poll() is not None: - break - - return_code = process.wait() - - append_output( - self.output_area, - "\nProcess finished with return code %s.\n" - % return_code, - ) - - except Exception as error: - append_output( - self.output_area, - "\nLauncher error: %s\n" % error, - ) - - finally: - if process is not None and process.stdout is not None: - try: - process.stdout.close() - except Exception: - pass - - System.clearProperty(RUNNING_PROPERTY) - - -# --------------------------------------------------------------------------- -# Script-selection dialog -# --------------------------------------------------------------------------- - def describe_script_context(script): """Return a short description of a script's requested capabilities.""" parts = ["CDA: %s" % script.get("cda", CDA_NONE)] @@ -694,7 +122,7 @@ def __init__(self, selector, argument_field, context_field): def actionPerformed(self, event): index = self.selector.getSelectedIndex() script = SCRIPTS[index] - self.argument_field.setText(script["args"]) + self.argument_field.setText(script.get("args", "")) self.context_field.setText(describe_script_context(script)) @@ -708,7 +136,7 @@ def show_launcher(): ) return - if System.getProperty(RUNNING_PROPERTY) == "true": + if is_script_running(): JOptionPane.showMessageDialog( None, "A Python job launched by this tool is already running.", @@ -721,7 +149,7 @@ def show_launcher(): for script in SCRIPTS: selector.addItem(script["name"]) - argument_field = JTextField(SCRIPTS[0]["args"], 70) + argument_field = JTextField(SCRIPTS[0].get("args", ""), 70) context_field = JTextField(describe_script_context(SCRIPTS[0]), 70) context_field.setEditable(False) selector.addActionListener( @@ -748,24 +176,7 @@ def show_launcher(): return selected_script = SCRIPTS[selector.getSelectedIndex()] - argument_text = str(argument_field.getText()) - - output_area = create_output_window( - selected_script["name"] - ) - - System.setProperty(RUNNING_PROPERTY, "true") - - worker = Thread( - ChildProcessRunner( - selected_script, - argument_text, - output_area, - ), - "RTS-CPython-Launcher", - ) - worker.setDaemon(True) - worker.start() + launch_script(selected_script, argument_field.getText()) class ShowLauncher(Runnable): diff --git a/jython_scripts/rts_cpython_bridge.py b/jython_scripts/rts_cpython_bridge.py new file mode 100644 index 0000000..5917ee4 --- /dev/null +++ b/jython_scripts/rts_cpython_bridge.py @@ -0,0 +1,767 @@ +# Reusable RTS Jython 2.7 bridge for external CPython scripts. +# +# Requirements: +# 1. Set PYTHON_CWMS_HOME to the directory containing python.exe. +# 2. CDA_AUTH normally uses an active RTS CDA login; disconnected launches +# require operator confirmation. + +import json +import os +import shlex +import subprocess + +from com.auth0.jwt import JWT +from java.awt import BorderLayout +from java.lang import NoSuchFieldException, Runnable, System, Thread +from java.time import ZonedDateTime +from java.time.format import DateTimeFormatter +from javax.swing import ( + JFrame, + JOptionPane, + JScrollPane, + JTextArea, + SwingUtilities, +) + +from hec.serversuite import ServerSuiteUtil +from hec2.rts.script import RTS +from hec2.rts.ui import ForecastTab +from hec2.rts.ui.tree import ModelAlternativeTreeNode +from mil.army.usace.hec.serversuite.cda import CdaAuthenticationSource + + +# --------------------------------------------------------------------------- +# Configuration +# --------------------------------------------------------------------------- + +PYTHON_HOME_ENV = "PYTHON_CWMS_HOME" +RUNNING_PROPERTY = "rts.cpython.launcher.running" + +CDA_NONE = "none" +CDA_ENDPOINT = "endpoint" +CDA_AUTH = "auth" + +CDA_ENVIRONMENT = ( + "CDA_API_ROOT", + "CDA_API_KEY", + "CDA_ACCESS_TOKEN", + "CDA_REFRESH_TOKEN", + "CDA_TOKEN_URL", + "CDA_CLIENT_ID", + "OFFICE", +) + +# Environment variables controlled by this launcher. Clear them before +# configuring each child so scripts cannot inherit credentials accidentally. +MANAGED_ENVIRONMENT = CDA_ENVIRONMENT + ( + "RTS_CONTEXT_JSON", + "RTS_WATERSHED_NAME", + "RTS_WATERSHED_DIRECTORY", + "RTS_WATERSHED_TIME_ZONE", + "RTS_CURRENT_MODULE", + "RTS_ACTIVE_FORECAST", + "RTS_ACTIVE_FORECAST_DIRECTORY", + "RTS_ACTIVE_FORECAST_DSS", + "RTS_ACTIVE_RUN", + "RTS_ACTIVE_RUN_KEY", + "RTS_SELECTED_MODEL_ALTERNATIVE", + "RTS_SELECTED_MODEL_ALTERNATIVE_PROGRAM", + "RTS_SELECTED_MODEL_ALTERNATIVE_F_PART", + "RTS_START_TIME", + "RTS_EXTRACT_START_TIME", + "RTS_FORECAST_TIME", + "RTS_END_TIME", +) + +# --------------------------------------------------------------------------- +# RTS authentication +# --------------------------------------------------------------------------- + +def get_private_field(obj, field_name): + """Read a private field from an object or one of its Java superclasses.""" + java_class = obj.getClass() + + while java_class is not None: + try: + field = java_class.getDeclaredField(field_name) + field.setAccessible(True) + return field.get(obj) + except NoSuchFieldException: + java_class = java_class.getSuperclass() + + raise RuntimeError( + "Field %s was not found on %s" + % (field_name, obj.getClass().getName()) + ) + + +def get_active_cda(): + """Return the active CDA source and data-access factory.""" + source = ServerSuiteUtil.getCwmsAuthenticationSource() + if not isinstance(source, CdaAuthenticationSource): + raise RuntimeError( + "This script requires an active RTS CDA connection" + ) + + factory = ServerSuiteUtil.getDataAccessFactory() + if factory is None: + raise RuntimeError( + "RTS does not have an active CDA DataAccessFactory" + ) + + return source, factory + + +def get_token_remaining_seconds(oauth_token): + """Return the access token's remaining lifetime.""" + access_token = oauth_token.getAccessToken() + if access_token is None or not str(access_token).strip(): + raise RuntimeError("The cached RTS access token is empty") + + expires_at = JWT.decode(str(access_token)).getExpiresAt() + if expires_at is None: + raise RuntimeError("The cached RTS access token has no expiration") + + remaining_millis = expires_at.getTime() - System.currentTimeMillis() + return max(0, int(remaining_millis / 1000)) + + +def refresh_token_before_launch(provider, oauth_token): + """Refresh through RTS immediately before launching CPython.""" + previous_remaining_seconds = get_token_remaining_seconds(oauth_token) + refresh_token = oauth_token.getRefreshToken() + if refresh_token is None or not str(refresh_token).strip(): + raise RuntimeError( + "The cached RTS OAuth token has no refresh token" + ) + + try: + oauth_token = provider.refreshToken() + except Exception as error: + raise RuntimeError( + "RTS could not refresh the CDA token. " + "Log out and back into CDA, then try again. %s" % error + ) + + if oauth_token is None: + raise RuntimeError("RTS returned no token after refresh") + + return ( + oauth_token, + get_token_remaining_seconds(oauth_token), + previous_remaining_seconds, + ) + + +def add_cda_environment( + child_env, + cda_mode, + allow_disconnected_cda=False, +): + """Add the requested level of CDA context to a child environment.""" + if cda_mode == CDA_NONE: + return None + + source, factory = get_active_cda() + child_env["CDA_API_ROOT"] = str(factory.getDataSourceUrl()) + child_env["OFFICE"] = str(factory.getOfficeId()) + + if cda_mode == CDA_ENDPOINT: + return None + + if cda_mode != CDA_AUTH: + raise RuntimeError("Unknown CDA mode: %s" % cda_mode) + + if ( + not ServerSuiteUtil.isConnected() + and not allow_disconnected_cda + ): + raise RuntimeError( + "This script requires an authenticated RTS CDA connection" + ) + + auth_optional = source.getCdaAuthExtension() + if not auth_optional.isPresent(): + raise RuntimeError( + "The active CDA connection has no authentication extension" + ) + + auth = auth_optional.get() + auth_type = str(auth.getExtensionType().name()) + if auth_type not in ("OPEN_ID", "OPEN_ID_CWBI"): + raise RuntimeError( + "RTS authentication type %s does not use an OAuth bearer token" + % auth_type + ) + + # Read the token created by the completed RTS login. Calling getToken() + # here could start another interactive OpenID login. + provider = get_private_field(auth, "_tokenProvider") + if provider is None: + raise RuntimeError( + "RTS has no cached token provider. " + "Log out and back into CDA, then try again." + ) + + oauth_token = get_private_field(provider, "token") + if oauth_token is None: + raise RuntimeError( + "RTS has no cached OAuth token. " + "Log out and back into CDA, then try again." + ) + + ( + oauth_token, + remaining_seconds, + previous_remaining_seconds, + ) = refresh_token_before_launch(provider, oauth_token) + access_token = oauth_token.getAccessToken() + refresh_token = oauth_token.getRefreshToken() + if access_token is None or not str(access_token).strip(): + raise RuntimeError("The cached RTS access token is empty") + if refresh_token is None or not str(refresh_token).strip(): + raise RuntimeError( + "The RTS OAuth response did not include a refresh token" + ) + + child_env["CDA_ACCESS_TOKEN"] = str(access_token) + child_env["CDA_REFRESH_TOKEN"] = str(refresh_token) + child_env["CDA_TOKEN_URL"] = str( + provider.getTokenUrl().getApiRoot() + ) + child_env["CDA_CLIENT_ID"] = str( + System.getProperty( + "hec.serversuite.cwbi.client.id.cda", + "cwms", + ) + ) + + return { + "lifetime_seconds": oauth_token.getExpiresIn(), + "remaining_seconds": remaining_seconds, + "previous_remaining_seconds": previous_remaining_seconds, + "refreshed": True, + } + + +def format_hec_time(hec_time, zone_id): + """Format a defined HecTime as an ISO-8601 timestamp with offset.""" + if hec_time is None or not hec_time.isDefined(): + return None + + instant = hec_time.getInstant(zone_id) + return str( + ZonedDateTime.ofInstant(instant, zone_id).format( + DateTimeFormatter.ISO_OFFSET_DATE_TIME + ) + ) + + +def add_rts_context_environment(child_env): + """Add a versioned snapshot of the current RTS context.""" + context = { + "version": 1, + "watershed": None, + "current_module": None, + "active_forecast": None, + "active_run": None, + "selected_model_alternative": None, + "time_window": None, + } + + watershed = RTS.getWatershed() + zone_id = None + if watershed is not None: + time_zone = watershed.getTimeZone() + zone_id = time_zone.toZoneId() + watershed_context = { + "name": str(watershed.getName()), + "directory": str(watershed.getProjectDirectory()), + "time_zone": str(time_zone.getID()), + } + context["watershed"] = watershed_context + child_env["RTS_WATERSHED_NAME"] = watershed_context["name"] + child_env["RTS_WATERSHED_DIRECTORY"] = watershed_context["directory"] + child_env["RTS_WATERSHED_TIME_ZONE"] = watershed_context["time_zone"] + + current_module = RTS.getCurrentModule() + if current_module is not None: + module_name = str(current_module.getTabTitle()) + context["current_module"] = module_name + child_env["RTS_CURRENT_MODULE"] = module_name + + if isinstance(current_module, ForecastTab): + selected_path = current_module.getSelectedTreePath() + selected_node = ( + selected_path.getLastPathComponent() + if selected_path is not None + else None + ) + if isinstance(selected_node, ModelAlternativeTreeNode): + model_alternative = selected_node.getModelAlternative() + f_part = model_alternative.getFpart() + model_alternative_context = { + "name": str(model_alternative.getName()), + "program": str(model_alternative.getProgram()), + "f_part": str(f_part) if f_part is not None else None, + } + context[ + "selected_model_alternative" + ] = model_alternative_context + child_env["RTS_SELECTED_MODEL_ALTERNATIVE"] = ( + model_alternative_context["name"] + ) + child_env["RTS_SELECTED_MODEL_ALTERNATIVE_PROGRAM"] = ( + model_alternative_context["program"] + ) + if model_alternative_context["f_part"] is not None: + child_env["RTS_SELECTED_MODEL_ALTERNATIVE_F_PART"] = ( + model_alternative_context["f_part"] + ) + + forecast = current_module.getForecast() + if forecast is not None: + forecast_context = { + "name": str(forecast.getName()), + "directory": str(forecast.getForecastDirectory()), + "dss_file": str(forecast.getForecastDSSFilename()), + } + context["active_forecast"] = forecast_context + child_env["RTS_ACTIVE_FORECAST"] = forecast_context["name"] + child_env["RTS_ACTIVE_FORECAST_DIRECTORY"] = ( + forecast_context["directory"] + ) + child_env["RTS_ACTIVE_FORECAST_DSS"] = forecast_context["dss_file"] + + forecast_run = current_module.getActiveForecastRun() + if forecast_run is not None: + run_context = { + "name": str(forecast_run.getName()), + "key": str(forecast_run.getKey()), + } + context["active_run"] = run_context + child_env["RTS_ACTIVE_RUN"] = run_context["name"] + child_env["RTS_ACTIVE_RUN_KEY"] = run_context["key"] + + # RTS calls the simulation start "lookback time" internally. + # The Forecast Time Window UI maps the four fields as follows. + run_time_window = ( + forecast_run.getRunTimeWindow() + if forecast_run is not None + else forecast.getRunTimeWindow() + ) + if run_time_window is not None and zone_id is not None: + time_window_context = { + "startTime": format_hec_time( + run_time_window.getLookbackTime(), + zone_id, + ), + "extractStartTime": format_hec_time( + run_time_window.getExtractStartTime(), + zone_id, + ), + "forecastTime": format_hec_time( + run_time_window.getStartTime(), + zone_id, + ), + "endTime": format_hec_time( + run_time_window.getEndTime(), + zone_id, + ), + } + context["time_window"] = time_window_context + + time_environment = ( + ("RTS_START_TIME", "startTime"), + ("RTS_EXTRACT_START_TIME", "extractStartTime"), + ("RTS_FORECAST_TIME", "forecastTime"), + ("RTS_END_TIME", "endTime"), + ) + for environment_name, context_name in time_environment: + value = time_window_context[context_name] + if value is not None: + child_env[environment_name] = value + + child_env["RTS_CONTEXT_JSON"] = json.dumps(context, sort_keys=True) + + +def build_child_environment(script, allow_disconnected_cda=False): + """Build only the environment capabilities requested by a script.""" + child_env = os.environ.copy() + for name in MANAGED_ENVIRONMENT: + child_env.pop(name, None) + + cda_mode = script.get("cda", CDA_NONE) + cda_error = None + try: + token_info = add_cda_environment( + child_env, + cda_mode, + allow_disconnected_cda, + ) + except Exception as error: + if not allow_disconnected_cda: + raise + + for name in CDA_ENVIRONMENT: + child_env.pop(name, None) + token_info = None + cda_error = str(error) + + if script.get("rts_context", False): + add_rts_context_environment(child_env) + + child_env["PYTHONUNBUFFERED"] = "1" + return child_env, token_info, cda_error + + +# --------------------------------------------------------------------------- +# Command-line handling +# --------------------------------------------------------------------------- + +def split_arguments(argument_text): + """Split editable Windows-style arguments into a subprocess argument list.""" + if not argument_text or not argument_text.strip(): + return [] + + values = shlex.split(str(argument_text), posix=False) + result = [] + + # shlex with posix=False preserves surrounding quotes. Remove those + # quotes because Popen receives an argument list rather than a shell line. + for value in values: + if ( + len(value) >= 2 + and value[0] == value[-1] + and value[0] in ("'", '"') + ): + value = value[1:-1] + + result.append(value) + + return result + + +def resolve_script_path(script): + """Resolve an absolute path or a path relative to script_directory.""" + script_path = str(script["path"]) + if os.path.isabs(script_path): + return os.path.normpath(script_path) + + script_directory = script.get("script_directory") + if not script_directory: + raise RuntimeError( + "Relative Python script path '%s' requires script_directory" + % script_path + ) + + script_directory = str(script_directory) + if not os.path.isabs(script_directory): + raise RuntimeError( + "script_directory must be an absolute path: %s" + % script_directory + ) + + return os.path.normpath( + os.path.join(script_directory, script_path) + ) + + +# --------------------------------------------------------------------------- +# Live output window +# --------------------------------------------------------------------------- + +class AppendOutput(Runnable): + def __init__(self, output_area, text): + self.output_area = output_area + self.text = text + + def run(self): + self.output_area.append(self.text) + document = self.output_area.getDocument() + self.output_area.setCaretPosition(document.getLength()) + + +def append_output(output_area, text): + """Append text safely from the process thread to the Swing UI.""" + SwingUtilities.invokeLater(AppendOutput(output_area, text)) + + +def create_output_window(script_name): + """Create and display a window for live subprocess output.""" + output_area = JTextArea(30, 110) + output_area.setEditable(False) + output_area.setLineWrap(False) + + frame = JFrame("Python Output: %s" % script_name) + frame.setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE) + frame.getContentPane().setLayout(BorderLayout()) + frame.getContentPane().add( + JScrollPane(output_area), + BorderLayout.CENTER, + ) + frame.pack() + frame.setLocationRelativeTo(None) + frame.setVisible(True) + + return output_area + + +# --------------------------------------------------------------------------- +# Background process +# --------------------------------------------------------------------------- + +class ChildProcessRunner(Runnable): + def __init__( + self, + selected_script, + argument_text, + output_area, + allow_disconnected_cda, + ): + self.selected_script = selected_script + self.argument_text = argument_text + self.output_area = output_area + self.allow_disconnected_cda = allow_disconnected_cda + + def run(self): + process = None + + try: + python_home = os.environ.get(PYTHON_HOME_ENV) + if not python_home: + raise RuntimeError( + "%s environment variable is not set" + % PYTHON_HOME_ENV + ) + + python_executable = os.path.join( + python_home, + "python.exe", + ) + script_path = resolve_script_path(self.selected_script) + + if not os.path.isfile(python_executable): + raise RuntimeError( + "Python executable not found: %s" + % python_executable + ) + + if not os.path.isfile(script_path): + raise RuntimeError( + "Python script not found: %s" % script_path + ) + + append_output( + self.output_area, + "Preparing requested runtime context...\n", + ) + + child_env, token_info, cda_error = build_child_environment( + self.selected_script, + self.allow_disconnected_cda, + ) + + child_env["PATH"] = ( + python_home + + os.pathsep + + child_env.get("PATH", "") + ) + + # -u makes stdin, stdout, and stderr unbuffered in CPython. + command = [python_executable, "-u", script_path] + command.extend(split_arguments(self.argument_text)) + + append_output( + self.output_area, + "\nStarting command:\n%s\n\n" + % subprocess.list2cmdline(command), + ) + append_output( + self.output_area, + "CDA context: %s\n" + % self.selected_script.get("cda", CDA_NONE), + ) + if "CDA_API_ROOT" in child_env: + append_output( + self.output_area, + "CDA_API_ROOT: %s\n" % child_env["CDA_API_ROOT"], + ) + append_output( + self.output_area, + "OFFICE: %s\n" % child_env["OFFICE"], + ) + if token_info is not None: + append_output( + self.output_area, + "Access-token lifetime: %s seconds\n" + % token_info["lifetime_seconds"], + ) + append_output( + self.output_area, + "Access token before refresh: %s seconds remaining\n" + % token_info["previous_remaining_seconds"], + ) + append_output( + self.output_area, + "Access token at launch: %s seconds remaining\n" + % token_info["remaining_seconds"], + ) + append_output( + self.output_area, + "Pre-launch token refresh: %s\n" + % ("yes" if token_info["refreshed"] else "not needed"), + ) + if cda_error is not None: + append_output( + self.output_area, + ( + "CDA context unavailable; continuing without it: " + "%s\n" % cda_error + ), + ) + append_output( + self.output_area, + "RTS context snapshot: %s\n\n" + % ( + "enabled" + if self.selected_script.get("rts_context", False) + else "disabled" + ), + ) + + # Never print CDA_ACCESS_TOKEN or CDA_REFRESH_TOKEN. + process = subprocess.Popen( + command, + cwd=os.path.dirname(script_path), + env=child_env, + stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, + ) + + # Stream output instead of waiting for communicate() to return. + while True: + line = process.stdout.readline() + + if line: + try: + text = line.decode("utf-8", "replace") + except AttributeError: + text = str(line) + + append_output(self.output_area, text) + elif process.poll() is not None: + break + + return_code = process.wait() + + append_output( + self.output_area, + "\nProcess finished with return code %s.\n" + % return_code, + ) + + except Exception as error: + append_output( + self.output_area, + "\nLauncher error: %s\n" % error, + ) + + finally: + if process is not None and process.stdout is not None: + try: + process.stdout.close() + except Exception: + pass + + System.clearProperty(RUNNING_PROPERTY) + + +# --------------------------------------------------------------------------- +# Public launch entry point +# --------------------------------------------------------------------------- + +def is_script_running(): + """Return whether this bridge already has a child process running.""" + return System.getProperty(RUNNING_PROPERTY) == "true" + + +def _start_script(script, argument_text): + """Create the output window and start a configured script.""" + if is_script_running(): + JOptionPane.showMessageDialog( + None, + "A Python job launched by this tool is already running.", + "Python Launcher", + JOptionPane.WARNING_MESSAGE, + ) + return + + if "name" not in script or "path" not in script: + JOptionPane.showMessageDialog( + None, + "A script configuration requires name and path.", + "Python Launcher", + JOptionPane.ERROR_MESSAGE, + ) + return + + allow_disconnected_cda = False + if ( + script.get("cda", CDA_NONE) == CDA_AUTH + and not ServerSuiteUtil.isConnected() + ): + choice = JOptionPane.showConfirmDialog( + None, + ( + "You are not connected to CDA, " + "do you want to run the script anyway?" + ), + "CDA Connection", + JOptionPane.YES_NO_OPTION, + JOptionPane.WARNING_MESSAGE, + ) + if choice != JOptionPane.YES_OPTION: + return + allow_disconnected_cda = True + + output_area = create_output_window(script["name"]) + System.setProperty(RUNNING_PROPERTY, "true") + + worker = Thread( + ChildProcessRunner( + script, + argument_text, + output_area, + allow_disconnected_cda, + ), + "RTS-CPython-Launcher", + ) + worker.setDaemon(True) + worker.start() + + +class StartScript(Runnable): + def __init__(self, script, argument_text): + self.script = script + self.argument_text = argument_text + + def run(self): + _start_script(self.script, self.argument_text) + + +def launch_script(script, argument_text=None): + """Launch one configured CPython script from RTS. + + If argument_text is omitted, the script's configured args value is used. + Swing components are always created on the event-dispatch thread. + """ + if argument_text is None: + argument_text = script.get("args", "") + + starter = StartScript(script, str(argument_text)) + + if SwingUtilities.isEventDispatchThread(): + starter.run() + else: + SwingUtilities.invokeAndWait(starter) From 0a0a2c6257d1480753c27c197a390cfec8dc080d Mon Sep 17 00:00:00 2001 From: msweier Date: Mon, 16 Nov 2026 10:03:24 -0600 Subject: [PATCH 4/7] setup default bridge directory --- jython_scripts/README.md | 22 +++++++++++++------ .../example_direct_python_script_launcher.py | 16 ++++++++++---- .../example_python_script_launcher.py | 16 ++++++++++---- 3 files changed, 39 insertions(+), 15 deletions(-) diff --git a/jython_scripts/README.md b/jython_scripts/README.md index 8bfc700..3b927b6 100644 --- a/jython_scripts/README.md +++ b/jython_scripts/README.md @@ -68,9 +68,10 @@ running child process. 3. Confirm that `%PYTHON_CWMS_HOME%\python.exe` exists. 4. Log in to a CDA connection in RTS before running an entry configured with `CDA_AUTH`. -5. Put `rts_cpython_bridge.py` in a stable directory. Set the - `RTS_CPYTHON_BRIDGE_HOME` user environment variable to that directory and - restart RTS, or edit `BRIDGE_DIRECTORY` near the top of each entry point. +5. Confirm that `rts_cpython_bridge.py` exists in the installed + `jython_scripts` directory beside the `python` directory. To keep the + bridge elsewhere, set the `RTS_CPYTHON_BRIDGE_HOME` user environment + variable to that directory and restart RTS. RTS evaluates button scripts as strings and does not automatically add the entry-point file's directory to Jython's module search path. The entry points @@ -127,10 +128,14 @@ file. import os import sys -BRIDGE_DIRECTORY = os.environ.get( - "RTS_CPYTHON_BRIDGE_HOME", - r"C:\code\pythonCWMS\jython_scripts", -) +PYTHON_HOME_ENV = "PYTHON_CWMS_HOME" +BRIDGE_DIRECTORY_ENV = "RTS_CPYTHON_BRIDGE_HOME" +BRIDGE_DIRECTORY = os.environ.get(BRIDGE_DIRECTORY_ENV) +if not BRIDGE_DIRECTORY: + BRIDGE_DIRECTORY = os.path.join( + os.path.dirname(os.path.normpath(os.environ[PYTHON_HOME_ENV])), + "jython_scripts", + ) if BRIDGE_DIRECTORY not in sys.path: sys.path.insert(0, BRIDGE_DIRECTORY) @@ -280,6 +285,9 @@ forecast-tree node is not a model alternative. - `Python executable not found`: verify that `PYTHON_CWMS_HOME` points to the directory containing `python.exe`, normally `C:\hec\python\pythonCWMS\python`. +- `RTS CPython bridge not found`: verify that the bridge is installed under + `%PYTHON_CWMS_HOME%\..\jython_scripts`, or set + `RTS_CPYTHON_BRIDGE_HOME` to its directory. - `This script requires an active RTS CDA connection`: select a CDA connection in RTS or change the entry to `CDA_NONE`. - Token or authentication errors: log out of CDA in RTS, log back in, and diff --git a/jython_scripts/example_direct_python_script_launcher.py b/jython_scripts/example_direct_python_script_launcher.py index 34a1042..8c6b629 100644 --- a/jython_scripts/example_direct_python_script_launcher.py +++ b/jython_scripts/example_direct_python_script_launcher.py @@ -7,11 +7,19 @@ import sys +PYTHON_HOME_ENV = "PYTHON_CWMS_HOME" BRIDGE_DIRECTORY_ENV = "RTS_CPYTHON_BRIDGE_HOME" -BRIDGE_DIRECTORY = os.environ.get( - BRIDGE_DIRECTORY_ENV, - r"C:\code\pythonCWMS\jython_scripts", -) +BRIDGE_DIRECTORY = os.environ.get(BRIDGE_DIRECTORY_ENV) +if not BRIDGE_DIRECTORY: + python_home = os.environ.get(PYTHON_HOME_ENV) + if not python_home: + raise RuntimeError( + "%s environment variable is not set" % PYTHON_HOME_ENV + ) + BRIDGE_DIRECTORY = os.path.join( + os.path.dirname(os.path.normpath(python_home)), + "jython_scripts", + ) BRIDGE_PATH = os.path.join( BRIDGE_DIRECTORY, "rts_cpython_bridge.py", diff --git a/jython_scripts/example_python_script_launcher.py b/jython_scripts/example_python_script_launcher.py index 0e3611a..11932f9 100644 --- a/jython_scripts/example_python_script_launcher.py +++ b/jython_scripts/example_python_script_launcher.py @@ -18,11 +18,19 @@ ) +PYTHON_HOME_ENV = "PYTHON_CWMS_HOME" BRIDGE_DIRECTORY_ENV = "RTS_CPYTHON_BRIDGE_HOME" -BRIDGE_DIRECTORY = os.environ.get( - BRIDGE_DIRECTORY_ENV, - r"C:\code\pythonCWMS\jython_scripts", -) +BRIDGE_DIRECTORY = os.environ.get(BRIDGE_DIRECTORY_ENV) +if not BRIDGE_DIRECTORY: + python_home = os.environ.get(PYTHON_HOME_ENV) + if not python_home: + raise RuntimeError( + "%s environment variable is not set" % PYTHON_HOME_ENV + ) + BRIDGE_DIRECTORY = os.path.join( + os.path.dirname(os.path.normpath(python_home)), + "jython_scripts", + ) BRIDGE_PATH = os.path.join( BRIDGE_DIRECTORY, "rts_cpython_bridge.py", From e9e44ef51de9dda565a0d07a6c59959b5d36adc8 Mon Sep 17 00:00:00 2001 From: msweier Date: Mon, 16 Nov 2026 10:05:31 -0600 Subject: [PATCH 5/7] use rts watershed/scripts as default launcher directory --- jython_scripts/README.md | 19 +++++++++++++++---- .../example_direct_python_script_launcher.py | 11 ++++++++++- 2 files changed, 25 insertions(+), 5 deletions(-) diff --git a/jython_scripts/README.md b/jython_scripts/README.md index 3b927b6..c4d571c 100644 --- a/jython_scripts/README.md +++ b/jython_scripts/README.md @@ -128,6 +128,8 @@ file. import os import sys +from hec2.rts.script import RTS + PYTHON_HOME_ENV = "PYTHON_CWMS_HOME" BRIDGE_DIRECTORY_ENV = "RTS_CPYTHON_BRIDGE_HOME" BRIDGE_DIRECTORY = os.environ.get(BRIDGE_DIRECTORY_ENV) @@ -141,7 +143,14 @@ if BRIDGE_DIRECTORY not in sys.path: from rts_cpython_bridge import CDA_AUTH, launch_script -SCRIPT_DIRECTORY = BRIDGE_DIRECTORY +watershed = RTS.getWatershed() +if watershed is None: + raise RuntimeError("No RTS watershed is open") + +SCRIPT_DIRECTORY = os.path.join( + str(watershed.getProjectDirectory()), + "scripts", +) SCRIPT = { "name": "Daily Regulation Sheet", @@ -157,9 +166,9 @@ launch_script(SCRIPT) Clicking the button bypasses the dropdown and argument editor. The live output window still opens so progress and errors remain visible. The direct entry point and dropdown use the same bridge, including the one-child-process limit -and CDA credential handling. When all files are together, leave -`SCRIPT_DIRECTORY` set to `BRIDGE_DIRECTORY`. Otherwise, set it to the -absolute directory containing the target CPython script. +and CDA credential handling. By default, `SCRIPT_DIRECTORY` is the `scripts` +directory under the active RTS watershed. Set it to another absolute directory +when the target CPython script is stored elsewhere. ### CDA access @@ -288,6 +297,8 @@ forecast-tree node is not a model alternative. - `RTS CPython bridge not found`: verify that the bridge is installed under `%PYTHON_CWMS_HOME%\..\jython_scripts`, or set `RTS_CPYTHON_BRIDGE_HOME` to its directory. +- `No RTS watershed is open`: open the target watershed before using a + one-click launcher that resolves its script from the watershed directory. - `This script requires an active RTS CDA connection`: select a CDA connection in RTS or change the entry to `CDA_NONE`. - Token or authentication errors: log out of CDA in RTS, log back in, and diff --git a/jython_scripts/example_direct_python_script_launcher.py b/jython_scripts/example_direct_python_script_launcher.py index 8c6b629..30071e2 100644 --- a/jython_scripts/example_direct_python_script_launcher.py +++ b/jython_scripts/example_direct_python_script_launcher.py @@ -6,6 +6,8 @@ import os import sys +from hec2.rts.script import RTS + PYTHON_HOME_ENV = "PYTHON_CWMS_HOME" BRIDGE_DIRECTORY_ENV = "RTS_CPYTHON_BRIDGE_HOME" @@ -38,7 +40,14 @@ from rts_cpython_bridge import CDA_AUTH, launch_script -SCRIPT_DIRECTORY = os.path.dirname(os.path.abspath(__file__)) +watershed = RTS.getWatershed() +if watershed is None: + raise RuntimeError("No RTS watershed is open") + +SCRIPT_DIRECTORY = os.path.join( + str(watershed.getProjectDirectory()), + "scripts", +) SCRIPT = { "name": "Daily Regulation Sheet", From a741c2d46d514edf5b3820727466665f3df1cd5d Mon Sep 17 00:00:00 2001 From: msweier Date: Mon, 16 Nov 2026 15:47:58 -0600 Subject: [PATCH 6/7] update override if logged in via JDBC --- jython_scripts/README.md | 19 +++++++++++-------- jython_scripts/rts_cpython_bridge.py | 15 ++++++++++++++- 2 files changed, 25 insertions(+), 9 deletions(-) diff --git a/jython_scripts/README.md b/jython_scripts/README.md index c4d571c..c54846b 100644 --- a/jython_scripts/README.md +++ b/jython_scripts/README.md @@ -197,14 +197,14 @@ cwms.init_session( office_id = os.environ["OFFICE"] ``` -If RTS reports that it is not connected to CDA, the launcher asks whether to -run the script anyway. Choosing **No** cancels the launch. Choosing **Yes** -bypasses the RTS connection-state check for that run. The launcher uses the -active CDA source and cached OAuth context when they are still available. If -CDA context preparation fails, it reports the reason in the output window and -starts the child without CDA environment variables. This is useful for scripts -that are configred to fall back to another data source -when CDA requests fail. +If RTS does not have an active CDA source and data-access factory, the launcher +asks whether to run the script anyway. Choosing **No** cancels the launch. +Choosing **Yes** bypasses the CDA connection check for that run. The launcher +uses the active CDA source and cached OAuth context when they are still +available. If CDA context preparation fails, it reports the reason in the +output window and starts the child without CDA environment variables. This is +useful for scripts that are configured to fall back to another data source when +CDA requests fail. Before constructing a child environment, the launcher removes all CDA and RTS variables that it manages. It then adds only the capabilities requested by the selected entry, preventing a `CDA_NONE` or `CDA_ENDPOINT` script from @@ -301,6 +301,9 @@ forecast-tree node is not a model alternative. one-click launcher that resolves its script from the watershed directory. - `This script requires an active RTS CDA connection`: select a CDA connection in RTS or change the entry to `CDA_NONE`. +- Changes to `rts_cpython_bridge.py` are not visible in an RTS session that + already imported it: restart RTS to reload the bridge. Jython compiles the + module automatically; do not manually generate a class file. - Token or authentication errors: log out of CDA in RTS, log back in, and launch the script again. - `Python script not found`: correct the absolute `path` in the selected diff --git a/jython_scripts/rts_cpython_bridge.py b/jython_scripts/rts_cpython_bridge.py index 5917ee4..3e06060 100644 --- a/jython_scripts/rts_cpython_bridge.py +++ b/jython_scripts/rts_cpython_bridge.py @@ -112,6 +112,19 @@ def get_active_cda(): return source, factory +def is_active_cda_connected(): + """Return whether RTS has a connected CDA source and factory.""" + if not ServerSuiteUtil.isConnected(): + return False + + try: + get_active_cda() + except Exception: + return False + + return True + + def get_token_remaining_seconds(oauth_token): """Return the access token's remaining lifetime.""" access_token = oauth_token.getAccessToken() @@ -709,7 +722,7 @@ def _start_script(script, argument_text): allow_disconnected_cda = False if ( script.get("cda", CDA_NONE) == CDA_AUTH - and not ServerSuiteUtil.isConnected() + and not is_active_cda_connected() ): choice = JOptionPane.showConfirmDialog( None, From f9febc9e2abf9c8b1634a4992a12f0f8a8629aa5 Mon Sep 17 00:00:00 2001 From: msweier Date: Tue, 17 Nov 2026 06:57:42 -0600 Subject: [PATCH 7/7] add dss vue example and clarify scripts/python directory suggestion --- README.md | 26 +++-- jython_scripts/README.md | 97 +++++++++++++++++-- .../example_direct_python_script_launcher.py | 20 +++- .../example_dssvue_python_script_launcher.py | 82 ++++++++++++++++ .../example_python_script_launcher.py | 29 ++++-- 5 files changed, 228 insertions(+), 26 deletions(-) create mode 100644 jython_scripts/example_dssvue_python_script_launcher.py diff --git a/README.md b/README.md index 36985d3..e6a5122 100644 --- a/README.md +++ b/README.md @@ -66,18 +66,30 @@ pythonCWMS -m pip install package-name Packages included in releases are defined by [base requirements](requirements/base_requirements.txt) and [supplemental requirements](requirements/supplemental_requirements.txt), then resolved into the hash-pinned [Windows lock](requirements/locked.txt). -## RTS scripts +## HEC application scripts -Jython is still used inside RTS to launch external CPython processes. Configure -the `SCRIPTS` list in +Jython can launch external CPython processes from RTS or HEC-DSSVue. For RTS, +configure the `SCRIPTS` list in [example_python_script_launcher.py](jython_scripts/example_python_script_launcher.py) to provide a script menu, or use [example_direct_python_script_launcher.py](jython_scripts/example_direct_python_script_launcher.py) for a one-click RTS button. Both entry points support optional CDA credentials -and an optional snapshot of the active RTS forecast context. The launcher is -RTS-specific and does not run in HEC-DSSVue. - -See the [RTS launcher guide](jython_scripts/README.md#rts-cpython-launcher) for configuration, child-process environment variables, security considerations, and troubleshooting. +and an optional snapshot of the active RTS forecast context. For scripts kept +with an RTS watershed, the examples use the recommended +`\scripts\python` directory. These two launchers are RTS-specific +and do not run in HEC-DSSVue. + +For HEC-DSSVue, use the separate +[DSSVue launcher](jython_scripts/example_dssvue_python_script_launcher.py). +It can launch a script from any configured directory, including a watershed's +`scripts\python` directory, but does not provide RTS authentication or forecast +context. + +See the [RTS launcher guide](jython_scripts/README.md#rts-cpython-launcher) for +RTS configuration, child-process environment variables, security +considerations, and troubleshooting. See the +[DSSVue launcher guide](jython_scripts/README.md#hec-dssvue-cpython-launcher) +for standalone path and authentication guidance. Do not use the former Jython `install_python.py` workflow to install Python CWMS. The file remains as a compatibility notice for old bookmarks, while the signed Windows installer is documented in the [Jython migration guide](jython_scripts/README.md). Saved copies of the old installer are also stopped by the retirement document at the root of `main`. diff --git a/jython_scripts/README.md b/jython_scripts/README.md index c54846b..4773218 100644 --- a/jython_scripts/README.md +++ b/jython_scripts/README.md @@ -58,7 +58,8 @@ Together they provide: The launcher uses RTS-specific classes and is not compatible with HEC-DSSVue. It runs one child process at a time. Closing the output window does not stop a -running child process. +running child process. To launch CPython from HEC-DSSVue instead, use the +separate [DSSVue launcher](#hec-dssvue-cpython-launcher). ### Prerequisites @@ -87,12 +88,33 @@ requires an absolute `script_directory` from which it will be resolved. The `args`, `cda`, and `rts_context` options default to an empty string, `CDA_NONE`, and `False`. +The recommended watershed layout stores CPython scripts under +`\scripts\python`. This keeps them grouped with the watershed while +distinguishing them from the Jython entry points that RTS evaluates. The +directory is only an organization convention; the CPython scripts can also run +from a terminal or HEC-DSSVue. The example menu resolves that directory from +the watershed currently open in RTS: + ```python +import os + +from hec2.rts.script import RTS + +watershed = RTS.getWatershed() +if watershed is None: + raise RuntimeError("No RTS watershed is open") + +SCRIPT_DIRECTORY = os.path.join( + str(watershed.getProjectDirectory()), + "scripts", + "python", +) + SCRIPTS = [ { "name": "Local DSS Utility", "path": "local_dss_utility.py", - "script_directory": r"C:\code\tools", + "script_directory": SCRIPT_DIRECTORY, "args": r'--file "C:\data\forecast.dss"', "cda": CDA_NONE, "rts_context": True, @@ -107,6 +129,10 @@ SCRIPTS = [ ] ``` +An absolute path remains appropriate when a script is shared outside the +watershed. A launcher that uses `SCRIPT_DIRECTORY` requires an open watershed +when it starts. + Use an empty string for `args` when a script takes no arguments. The launcher splits the argument text using Windows-style quoting and passes an argument list directly to CPython without invoking a shell. The launch dialog lets the @@ -150,12 +176,22 @@ if watershed is None: SCRIPT_DIRECTORY = os.path.join( str(watershed.getProjectDirectory()), "scripts", + "python", ) +DOWNLOAD_DIRECTORY = os.path.join(os.environ["USERPROFILE"], "Downloads") + SCRIPT = { "name": "Daily Regulation Sheet", - "path": os.path.join(SCRIPT_DIRECTORY, "daily_reg_sheet.py"), - "args": "report --open", + "path": os.path.join( + SCRIPT_DIRECTORY, + "daily_reg_sheet_python.py", + ), + "args": ( + 'report --output-dir "{}" --no-log-file --open'.format( + DOWNLOAD_DIRECTORY + ) + ), "cda": CDA_AUTH, "rts_context": False, } @@ -166,9 +202,9 @@ launch_script(SCRIPT) Clicking the button bypasses the dropdown and argument editor. The live output window still opens so progress and errors remain visible. The direct entry point and dropdown use the same bridge, including the one-child-process limit -and CDA credential handling. By default, `SCRIPT_DIRECTORY` is the `scripts` -directory under the active RTS watershed. Set it to another absolute directory -when the target CPython script is stored elsewhere. +and CDA credential handling. By default, `SCRIPT_DIRECTORY` is the +`scripts\python` directory under the active RTS watershed. Set it to another +absolute directory when the target CPython script is stored elsewhere. ### CDA access @@ -307,8 +343,53 @@ forecast-tree node is not a model alternative. - Token or authentication errors: log out of CDA in RTS, log back in, and launch the script again. - `Python script not found`: correct the absolute `path` in the selected - `SCRIPTS` entry. + `SCRIPTS` entry, or confirm that the relative script exists under the + configured `script_directory` (by default, + `\scripts\python`). The authenticated mode reads RTS's cached token provider through Java reflection to avoid opening another interactive login. That implementation detail may need updating when moving the launcher to a different RTS release. + +## HEC-DSSVue CPython launcher + +Use +[`example_dssvue_python_script_launcher.py`](example_dssvue_python_script_launcher.py) +to start a CPython script from HEC-DSSVue. This entry point is intentionally +separate from `rts_cpython_bridge.py` because DSSVue does not provide the RTS +watershed, forecast, and CDA authentication classes used by the bridge. + +Edit `SCRIPT_DIRECTORY` to select the location of the CPython script. It does +not need to be in an RTS watershed: + +```python +SCRIPT_DIRECTORY = r"C:\code\python-tools" +``` + +A DSSVue button can also launch a script stored under an RTS watershed without +opening that watershed in RTS. Configure the watershed path explicitly: + +```python +SCRIPT_DIRECTORY = os.path.join( + r"C:\watersheds\example", + "scripts", + "python", +) +``` + +If the CPython script and Jython launcher are stored together, use: + +```python +SCRIPT_DIRECTORY = os.path.dirname(os.path.abspath(__file__)) +``` + +The example passes arguments as a list so directories containing spaces do not +require manual quoting. It waits for the child process and leaves standard +output and error attached to the DSSVue script console. + +The DSSVue launcher inherits normal environment variables but does not copy +credentials or context from RTS. A CPython script that calls CDA must obtain +its own credentials, such as `CDA_ACCESS_TOKEN` or `CDA_API_KEY`, from its +environment or its normal authentication workflow. As with the RTS launchers, +restart DSSVue after installing Python CWMS so it can see +`PYTHON_CWMS_HOME`. diff --git a/jython_scripts/example_direct_python_script_launcher.py b/jython_scripts/example_direct_python_script_launcher.py index 30071e2..49c5bfb 100644 --- a/jython_scripts/example_direct_python_script_launcher.py +++ b/jython_scripts/example_direct_python_script_launcher.py @@ -1,7 +1,8 @@ # RTS Jython 2.7 one-click entry point for one external CPython script. # -# Set BRIDGE_DIRECTORY to the directory containing rts_cpython_bridge.py, then -# assign this file to an RTS script button. +# The bridge is found beside Python CWMS by default. Set +# RTS_CPYTHON_BRIDGE_HOME to override its directory, then assign this file to +# an RTS script button. import os import sys @@ -44,15 +45,26 @@ if watershed is None: raise RuntimeError("No RTS watershed is open") +# Keep watershed-owned CPython scripts separate from Jython entry points. SCRIPT_DIRECTORY = os.path.join( str(watershed.getProjectDirectory()), "scripts", + "python", ) +DOWNLOAD_DIRECTORY = os.path.join(os.environ["USERPROFILE"], "Downloads") + SCRIPT = { "name": "Daily Regulation Sheet", - "path": os.path.join(SCRIPT_DIRECTORY, "daily_reg_sheet.py"), - "args": "report --open", + "path": os.path.join( + SCRIPT_DIRECTORY, + "daily_reg_sheet_python.py", + ), + "args": ( + 'report --output-dir "{}" --no-log-file --open'.format( + DOWNLOAD_DIRECTORY + ) + ), "cda": CDA_AUTH, "rts_context": False, } diff --git a/jython_scripts/example_dssvue_python_script_launcher.py b/jython_scripts/example_dssvue_python_script_launcher.py new file mode 100644 index 0000000..7b05e7e --- /dev/null +++ b/jython_scripts/example_dssvue_python_script_launcher.py @@ -0,0 +1,82 @@ +# HEC-DSSVue Jython 2.7 entry point for one external CPython script. +# +# This launcher does not use RTS classes or rts_cpython_bridge.py. Assign it to +# a DSSVue script button after choosing the CPython script directory below. + +import os +import subprocess + + +PYTHON_HOME_ENV = "PYTHON_CWMS_HOME" + +# Choose the directory containing the CPython script. +SCRIPT_DIRECTORY = r"C:\path\to\python\scripts" + +# A DSSVue launcher can target a script stored with an RTS watershed even +# though RTS is not running: +# +# SCRIPT_DIRECTORY = os.path.join( +# r"C:\watersheds\example", +# "scripts", +# "python", +# ) +# +# To keep the CPython script beside this Jython launcher instead: +# +# SCRIPT_DIRECTORY = os.path.dirname(os.path.abspath(__file__)) + +DOWNLOAD_DIRECTORY = os.path.join(os.environ["USERPROFILE"], "Downloads") +SCRIPT_PATH = os.path.join( + SCRIPT_DIRECTORY, + "daily_reg_sheet_python.py", +) + +# Use a list so spaces in paths remain part of the same argument. +SCRIPT_ARGUMENTS = [ + "report", + "--output-dir", + DOWNLOAD_DIRECTORY, + "--no-log-file", + "--open", +] + + +python_home = os.environ.get(PYTHON_HOME_ENV) +if not python_home: + raise RuntimeError( + "%s environment variable is not set" % PYTHON_HOME_ENV + ) + +python_executable = os.path.join(python_home, "python.exe") +if not os.path.isfile(python_executable): + raise RuntimeError( + "Python executable not found: %s" % python_executable + ) + +if not os.path.isfile(SCRIPT_PATH): + raise RuntimeError("Python script not found: %s" % SCRIPT_PATH) + +child_env = os.environ.copy() +child_env["PYTHONUNBUFFERED"] = "1" +child_env["PATH"] = ( + python_home + + os.pathsep + + child_env.get("PATH", "") +) + +command = [python_executable, "-u", SCRIPT_PATH] +command.extend(SCRIPT_ARGUMENTS) + +print("Starting command:") +print(subprocess.list2cmdline(command)) + +# Standard output and error remain attached to the DSSVue script console. +return_code = subprocess.call( + command, + cwd=os.path.dirname(SCRIPT_PATH), + env=child_env, +) +if return_code: + raise RuntimeError( + "Python script exited with return code %s" % return_code + ) diff --git a/jython_scripts/example_python_script_launcher.py b/jython_scripts/example_python_script_launcher.py index 11932f9..4c3d881 100644 --- a/jython_scripts/example_python_script_launcher.py +++ b/jython_scripts/example_python_script_launcher.py @@ -1,6 +1,7 @@ # RTS Jython 2.7 menu for launching configured external CPython scripts. # -# Set BRIDGE_DIRECTORY to the directory containing rts_cpython_bridge.py. +# The bridge is found beside Python CWMS by default. Set +# RTS_CPYTHON_BRIDGE_HOME to override its directory. import os import sys @@ -17,6 +18,8 @@ SwingUtilities, ) +from hec2.rts.script import RTS + PYTHON_HOME_ENV = "PYTHON_CWMS_HOME" BRIDGE_DIRECTORY_ENV = "RTS_CPYTHON_BRIDGE_HOME" @@ -61,19 +64,30 @@ # cda=CDA_AUTH Refresh, then pass RTS OAuth access/refresh credentials. # rts_context=True Pass a snapshot of the current watershed/forecast/run. # script_directory Absolute base directory for a relative path. +watershed = RTS.getWatershed() +if watershed is None: + raise RuntimeError("No RTS watershed is open") + +# Keep watershed-owned CPython scripts separate from Jython entry points. +SCRIPT_DIRECTORY = os.path.join( + str(watershed.getProjectDirectory()), + "scripts", + "python", +) + SCRIPTS = [ { "name": "Get MN DNR Data", - "path": r"C:\code\mvp-wm-cwbi-jobs\python\get_mndnr.py", + "path": "get_mndnr.py", + "script_directory": SCRIPT_DIRECTORY, "args": "-d 1", "cda": CDA_AUTH, "rts_context": False, }, { "name": "Get MN DNR Data - Selected Locations", - "path": ( - r"C:\code\mvp-wm-cwbi-jobs\python\get_mndnr.py" - ), + "path": "get_mndnr.py", + "script_directory": SCRIPT_DIRECTORY, "args": "-d 3 -l TMCM5 SPFM5", "cda": CDA_AUTH, "rts_context": False, @@ -92,10 +106,11 @@ # Examples for additional entries: # -# Local DSS script using the current watershed path, but no CDA variables: +# CPython scripts stored with the watershed use SCRIPT_DIRECTORY: # { # "name": "Local DSS Utility", -# "path": r"C:\code\tools\local_dss_utility.py", +# "path": "local_dss_utility.py", +# "script_directory": SCRIPT_DIRECTORY, # "args": "", # "cda": CDA_NONE, # "rts_context": True,