migrate Jython-based Java application to Python-based impl with JPype

- build orchestration with gradle

Author: adamkorynta

README.md

@@ -1,61 +1,100 @@
 # REGI-Headless
 
 > [!IMPORTANT]
-> **Notice: Project Refactor in Progress**
-> This project is undergoing a large refactor for CWMS Data API support. 
-> It will transition from a Java project consuming Jython scripts to a **Python project** that 
-> utilizes **JPype** to call underlying REGI Java libraries.
+> **Project Refactor in Progress**
+> This project has transitioned from a Java project consuming Jython scripts to a **Python bridge** that utilizes **JPype** to call underlying REGI Java libraries.
 
-`REGI-Headless` is a Java-based command-line tool and library designed to run 
-**REGI** calculations in a headless environment. 
-It allows users to execute complex hydrological calculations and manage gate settings via Jython 
-scripts without the need for a graphical interface.
+`REGI-Headless` provides a Python-based interface for running **REGI** calculations in a headless environment. It allows users to execute complex hydrological calculations and manage gate settings via Python scripts, leveraging the performance and stability of the original REGI Java libraries.
 
 ## Features
 
-- **Headless Execution**: Run REGI calculations as part of automated workflows or on servers.
-- **Database Integration**: Connects to CWMS data retrieval and storage.
-- **Modular Calculations**: Includes support for:
+- **Headless Execution**: Run REGI calculations as part of automated workflows, CI/CD pipelines, or on servers.
+- **Python-First API**: Write calculation scripts in standard Python 3.
+- **Java Interoperability**: Direct access to REGI Java libraries via JPype.
+- **Modular Calculations**: Full support for:
   - Inflow calculations (Clone, Compute, Auto-Adjust, Balance All, etc.)
-  - Flow Group and gate settings calculations.
+  - Flow Group
+  - Gate settings calculations.
 
 ## Project Structure
 
-- `regi-headless/`: Core Java implementation, including `RegiCLI`.
-- `district-scripts/`: Example scripts and district-specific configurations.
+- `regi-headless/`: Core implementation.
+  - `src/main/python/`: The `regi-python` package source.
+  - `src/main/java/`: Java-based headless support and factories.
+- `district-scripts/`: Legacy Jython scripts and district-specific configurations.
 - `docs/`: Additional documentation.
 
 ## Getting Started
 
 ### Prerequisites
 
-- Java JDK 21 or higher.
-- Access to a CWMS
+- **Java JDK 21** or higher.
+- **Python 3.11** or higher.
+- Access to a **CWMS Data API (CDA)** instance.
 
 ### Building
 
+The project uses Gradle to manage both Java and Python builds. To build the Python wheel including all Java dependencies:
 
 ```powershell
-./gradlew build
+./gradlew buildPythonWheel
 ```
 
-Details TBD.
+The resulting wheel file will be located in `regi-headless/build/install/regi-python/dist/`.
 
 ## Usage
 
-TBD
+### Installation
 
-### Command Line Options
+Install the built wheel into your Python environment:
 
-TBD
+```powershell
+pip install regi_python-*.whl
+```
+
+### Script Example
+
+The Python bridge uses a context manager to handle the JVM lifecycle and a callback mechanism for calculations.
+
+```python
+from regi_python import regi_session, run_headless
+from java.util import Calendar, TimeZone
+
+def my_calculations(registry):
+    # 'registry' is a RegiCalcRegistry instance
+    gate_calc = registry.getCalculation(1.0, "Gate Flow")
+    
+    # Configure time window
+    tz = TimeZone.getTimeZone("US/Central")
+    start = Calendar.getInstance(tz)
+    start.set(2025, 0, 1) # Jan 1, 2025
+    
+    end = Calendar.getInstance(tz)
+    end.set(2025, 0, 2) # Jan 2, 2025
+    
+    # Execute calculation
+    gate_calc.computeAll("OFFICE", "PROJECT", start.getTimeInMillis(), end.getTimeInMillis())
+
+if __name__ == "__main__":
+    with regi_session():
+        run_headless(my_calculations)
+```
 
-### Example
+### Environment Variables
 
-TBD
+- `JAVA_HOME`: Path to your Java installation (required for JPype).
+- `REGI_LOG_LEVEL`: Logging level (e.g., `DEBUG`, `INFO`, `ERROR`).
+- `CDA_URL`: URL for the CWMS Data API.
+- `CDA_API_KEY`: API Key for CDA authentication.
+- `OFFICE_ID`: Office ID for CDA authentication.
 
 ## Testing
 
-TBD
+To run the automated tests which build the wheel and execute a test script in a virtual environment:
+
+```powershell
+./gradlew testPythonWheel
+```
 
 ## Maintainers
 

build.gradle

@@ -3,14 +3,52 @@ plugins {
     id "org.sonarqube" version "7.3.1.8318"
 }
 
-def versionLabel(gitInfo) {
-    def branch = gitInfo.branchName // all branches are snapshots, only tags get released
-    def tag = gitInfo.lastTag
-    // tag is returned as is. Branch may need cleanup
-    return branch == null ? tag : "99." + branch.replace("/","-") + "-SNAPSHOT"
+def gitOutput(String... args) {
+    return providers.exec {
+        commandLine(['git'] + args.toList())
+        ignoreExitValue = true
+    }.standardOutput.asText.get().trim()
+}
+
+def pep440VersionFromLatestTag() {
+    def tag = gitOutput('describe', '--tags', '--abbrev=0')
+    if (!tag) {
+        tag = '0.0.0'
+    }
+
+    def baseVersion = tag.startsWith('v') ? tag.substring(1) : tag
+
+    def distanceText = tag == '0.0.0'
+            ? gitOutput('rev-list', 'HEAD', '--count')
+            : gitOutput('rev-list', "${tag}..HEAD", '--count')
+    def distance = distanceText?.isInteger() ? distanceText.toInteger() : 0
+
+    def hash = gitOutput('rev-parse', '--short=7', 'HEAD')
+    def dirty = gitOutput('status', '--porcelain') ? true : false
+
+    if (distance == 0 && !dirty) {
+        return baseVersion
+    }
+
+    def version = "${baseVersion}.post${distance}"
+    def localParts = []
+
+    if (hash) {
+        localParts.add("g${hash}")
+    }
+
+    if (dirty) {
+        localParts.add("dirty")
+    }
+
+    if (!localParts.isEmpty()) {
+        version += "+" + localParts.join(".")
+    }
+
+    return version
 }
 
 allprojects {
-    group = 'mil.army.wmist.regi-headless'
-    version = versionLabel(versionDetails())
+    group = 'mil.army.wmist.regi-python'
+    version = pep440VersionFromLatestTag()
 }

gradle/libs.versions.toml

@@ -36,6 +36,7 @@ regi-tools-regi-cwms = {module = "mil.army.wmist.regi-tools:regi-cwms", version.
 # Third Party
 jython-standalone = {module = "org.python:jython-standalone", version.ref = "jython-standalone"}
 args4j = {module = "args4j:args4j", version.ref = "args4j"}
+otel = {module = "io.opentelemetry:opentelemetry-api", version="1.58.0"}
 
 # Test
 junit-jupiter-api = { module = "org.junit.jupiter:junit-jupiter-api", version.ref = "junit" }

regi-headless/build.gradle

@@ -1,6 +1,9 @@
+import com.pswidersk.gradle.python.VenvTask
+
 plugins {
     id 'regi-headless.deps-conventions'
     id 'regi-headless.java-conventions'
+    id 'com.pswidersk.python-plugin' version '3.2.16'
 }
 
 dependencies {
@@ -45,6 +48,85 @@ jar {
     }
 }
 
-test {
-    useJUnitPlatform()
+pythonPlugin {
+    pythonVersion = "3.11.15"
+    condaVersion = "26.3.2-2"
+    condaInstaller = "Miniforge3"
+    installDir = file(layout.buildDirectory.dir("python"))
+}
+
+tasks.register('installPythonBuildTools', VenvTask) {
+    group = 'build setup'
+    description = 'Installs Python packages needed to build the wheel.'
+
+    venvExec = 'pip'
+    args = ['install', '--upgrade', 'pip', 'build']
+}
+
+tasks.register('buildPythonWheel', VenvTask) {
+    group = "distribution"
+    description = "Builds a Python .whl file using the Gradle-managed Python environment."
+
+    dependsOn bundlePython
+    dependsOn installPythonBuildTools
+
+    workingDir = file("${buildDir}/install/regi-python")
+    venvExec = "python"
+    args = ["-m", "build", "--wheel"]
+
+    doLast {
+        println "Python Wheel built in: ${workingDir}/dist"
+    }
+}
+
+tasks.register('bundlePython', Sync) {
+    description = 'Bundles Python scripts and creates the java_lib directory'
+    into "${buildDir}/install/regi-python/"
+
+    from('src/main/python') {
+        include 'pyproject.toml'
+        filter { line -> line.replaceAll('@VERSION@', project.version.toString()) }
+    }
+
+    from('src/main/python') {
+        exclude 'pyproject.toml'
+    }
+
+    into('regi-python/lib') {
+        from configurations.runtimeClasspath
+        from jar.archiveFile
+        exclude "**/*.nbm"
+    }
+}
+
+tasks.register('testPythonWheel') {
+    group = 'verification'
+    description = 'Creates a venv, installs the wheel, and runs a test script.'
+    dependsOn buildPythonWheel
+
+    doLast {
+        def venvName = "test_venv"
+        def wheelDir = "${projectDir}/build/install/regi-headless/dist"
+        def testScript = "src\\test\\resources\\usace\\rowcps\\headless\\examples\\GateFlowCalc2_Jpype.py"
+
+        // 1. Create VENV if it doesn't exist
+        exec {
+            commandLine 'cmd', '/c', "python -m venv ${venvName}"
+        }
+
+        // 2. Install Wheel and Run Script
+        // We chain these using '&&' so they run in the same shell session where the venv is active
+        exec {
+            workingDir projectDir
+            def wheelFile = fileTree(dir: wheelDir, include: '*.whl').singleFile.absolutePath
+            def venvActivate = file("${venvName}/Scripts/activate.bat").absolutePath
+            environment 'CDA_URL', project.findProperty('CDA_URL') ?: ""
+            environment 'API_KEY', project.findProperty('API_KEY') ?: ""
+            environment 'OFFICE_ID', project.findProperty('OFFICE_ID') ?: ""
+            environment 'JAVA_HOME', System.getProperty('java.home')
+            commandLine 'cmd', '/c', "\"${venvActivate}\" && pip install --force-reinstall \"${wheelFile}\" && python -u  ${testScript}"
+            standardOutput = System.out
+            errorOutput = System.err
+        }
+    }
 }