feat: add auto-fetch with cjdk

Author: tlambert03

.github/workflows/build.yml

@@ -26,6 +26,13 @@ jobs:
           '3.10',
           '3.12'
         ]
+        java-version: ['11']
+        include:
+          # one test without java to test cjdk fallback
+          - os: ubuntu-latest
+            python-version: '3.12'
+            java-version: ''
+
 
     steps:
     - uses: actions/checkout@v2
@@ -35,8 +42,9 @@ jobs:
         python-version: ${{matrix.python-version}}
 
     - uses: actions/setup-java@v3
+      if: matrix.java-version != ''
       with:
-        java-version: '11'
+        java-version: ${{matrix.java-version}}
         distribution: 'zulu'
         cache: 'maven'
 

dev-environment.yml

@@ -37,5 +37,6 @@ dependencies:
   # Project from source
   - pip
   - pip:
+    - cjdk
     - git+https://github.com/ninia/jep.git@cfca63f8b3398daa6d2685428660dc4b2bfab67d
     - -e .

pyproject.toml

@@ -39,7 +39,9 @@ dependencies = [
 
 [project.optional-dependencies]
 # NB: Keep this in sync with dev-environment.yml!
+cjdk = ["cjdk"]
 dev = [
+    "scyjava[cjdk]",
     "assertpy",
     "build",
     "jep",

src/scyjava/_cjdk_fetch.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import logging
+import os
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+_logger = logging.getLogger(__name__)
+_DEFAULT_MAVEN_URL = "tgz+https://dlcdn.apache.org/maven/maven-3/3.9.9/binaries/apache-maven-3.9.9-bin.tar.gz"  # noqa: E501
+_DEFAULT_MAVEN_SHA = "a555254d6b53d267965a3404ecb14e53c3827c09c3b94b5678835887ab404556bfaf78dcfe03ba76fa2508649dca8531c74bca4d5846513522404d48e8c4ac8b"  # noqa: E501
+_DEFAULT_JAVA_VENDOR = "zulu-jre"
+_DEFAULT_JAVA_VERSION = "11"
+
+
+def cjdk_fetch_java(
+    vendor: str = "", version: str = "", raise_on_error: bool = True
+) -> None:
+    """Fetch java using cjdk and add it to the PATH."""
+    try:
+        import cjdk
+    except ImportError as e:
+        if raise_on_error is True:
+            raise ImportError(
+                "No JVM found. Please install `cjdk` to use the fetch_java feature."
+            ) from e
+        _logger.info("cjdk is not installed. Skipping automatic fetching of java.")
+        return
+
+    if not vendor:
+        vendor = os.getenv("JAVA_VENDOR", _DEFAULT_JAVA_VENDOR)
+        version = os.getenv("JAVA_VERSION", _DEFAULT_JAVA_VERSION)
+
+    _logger.info(f"No JVM found, fetching {vendor}:{version} using cjdk...")
+    home = cjdk.java_home(vendor=vendor, version=version)
+    _add_to_path(str(home / "bin"))
+    os.environ["JAVA_HOME"] = str(home)
+
+
+def cjdk_fetch_maven(url: str = "", sha: str = "", raise_on_error: bool = True) -> None:
+    """Fetch Maven using cjdk and add it to the PATH."""
+    try:
+        import cjdk
+    except ImportError as e:
+        if raise_on_error is True:
+            raise ImportError(
+                "Please install `cjdk` to use the fetch_java feature."
+            ) from e
+        _logger.info("cjdk is not installed. Skipping automatic fetching of Maven.")
+        return
+
+    # if url was passed as an argument, or env_var, use it with provided sha
+    # otherwise, use default values for both
+    if url := url or os.getenv("MAVEN_URL", ""):
+        sha = sha or os.getenv("MAVEN_SHA", "")
+    else:
+        url = _DEFAULT_MAVEN_URL
+        sha = _DEFAULT_MAVEN_SHA
+
+    # fix urls to have proper prefix for cjdk
+    if url.startswith("http"):
+        if url.endswith(".tar.gz"):
+            url = url.replace("http", "tgz+http")
+        elif url.endswith(".zip"):
+            url = url.replace("http", "zip+http")
+
+    # determine sha type based on length (cjdk requires specifying sha type)
+    # assuming hex-encoded SHA, length should be 40, 64, or 128
+    kwargs = {}
+    if sha_len := len(sha):  # empty sha is fine... we just don't pass it
+        sha_lengths = {40: "sha1", 64: "sha256", 128: "sha512"}
+        if sha_len not in sha_lengths:
+            raise ValueError(
+                "MAVEN_SHA be a valid sha1, sha256, or sha512 hash."
+                f"Got invalid SHA length: {sha_len}. "
+            )
+        kwargs = {sha_lengths[sha_len]: sha}
+
+    maven_dir = cjdk.cache_package("Maven", url, **kwargs)
+    if maven_bin := next(maven_dir.rglob("apache-maven-*/**/mvn"), None):
+        _add_to_path(maven_bin.parent, front=True)
+    else:
+        raise RuntimeError("Failed to find Maven executable in the downloaded package.")
+
+
+def _add_to_path(path: Path | str, front: bool = False) -> None:
+    """Add a path to the PATH environment variable.
+
+    If front is True, the path is added to the front of the PATH.
+    By default, the path is added to the end of the PATH.
+    If the path is already in the PATH, it is not added again.
+    """
+
+    current_path = os.environ.get("PATH", "")
+    if (path := str(path)) in current_path:
+        return
+    new_path = [path, current_path] if front else [current_path, path]
+    os.environ["PATH"] = os.pathsep.join(new_path)

src/scyjava/_jvm.py

@@ -6,6 +6,7 @@
 import logging
 import os
 import re
+import shutil
 import subprocess
 import sys
 from functools import lru_cache
@@ -16,6 +17,7 @@
 import jpype.config
 from jgo import jgo
 
+from scyjava._cjdk_fetch import cjdk_fetch_java, cjdk_fetch_maven
 import scyjava.config
 from scyjava.config import Mode, mode
 
@@ -106,7 +108,7 @@ def jvm_version() -> str:
     return tuple(map(int, m.group(1).split(".")))
 
 
-def start_jvm(options=None) -> None:
+def start_jvm(options=None, *, fetch_java: bool | None = None) -> None:
     """
     Explicitly connect to the Java virtual machine (JVM). Only one JVM can
     be active; does nothing if the JVM has already been started. Calling
@@ -117,6 +119,13 @@ def start_jvm(options=None) -> None:
     :param options:
         List of options to pass to the JVM.
         For example: ['-Dfoo=bar', '-XX:+UnlockExperimentalVMOptions']
+    :param fetch_java:
+        Whether to automatically fetch a JRE (and/or maven) using
+        [`cjdk`](https://github.com/cachedjdk/cjdk) if java and maven executables are
+        not found. Requires `cjdk` to be installed. See README for details.
+            - If `None` (default), then fetching will only occur if `cjdk` is available.
+            - If `True`, an exception will be raised if `cjdk` is not available.
+            - If `False`, no attempt to import `cjdk` is be made.
     """
     # if JVM is already running -- break
     if jvm_started():
@@ -132,8 +141,14 @@ def start_jvm(options=None) -> None:
     # use the logger to notify user that endpoints are being added
     _logger.debug("Adding jars from endpoints {0}".format(endpoints))
 
+    if fetch_java is not False and not is_jvm_available():
+        cjdk_fetch_java(raise_on_error=fetch_java is True)
+
     # get endpoints and add to JPype class path
     if len(endpoints) > 0:
+        if not shutil.which("mvn") and fetch_java is not False:
+            cjdk_fetch_maven(raise_on_error=fetch_java is True)
+
         endpoints = endpoints[:1] + sorted(endpoints[1:])
         _logger.debug("Using endpoints %s", endpoints)
         _, workspace = jgo.resolve_dependencies(
@@ -340,6 +355,28 @@ def is_jvm_headless() -> bool:
     return bool(GraphicsEnvironment.isHeadless())
 
 
+def is_jvm_available() -> bool:
+    """
+    Return True if the JVM is available, suppressing stderr on macos.
+    """
+    from unittest.mock import patch
+
+    subprocess_check_output = subprocess.check_output
+
+    def _silent_check_output(*args, **kwargs):
+        # also suppress stderr on calls to subprocess.check_output
+        kwargs.setdefault("stderr", subprocess.DEVNULL)
+        return subprocess_check_output(*args, **kwargs)
+
+    try:
+        with patch.object(subprocess, "check_output", new=_silent_check_output):
+            jpype.getDefaultJVMPath()
+    # on Darwin, may raise a CalledProcessError when invoking `/user/libexec/java_home`
+    except (jpype.JVMNotFoundException, subprocess.CalledProcessError):
+        return False
+    return True
+
+
 def is_awt_initialized() -> bool:
     """
     Return true iff the AWT subsystem has been initialized.