Merge branch 'main' into stubs

Author: tlambert03

README.md

@@ -85,6 +85,24 @@ u'1.8.0_152-release'
 
 See the [jgo documentation](https://github.com/scijava/jgo) for more about Maven endpoints.
 
+## Bootstrap a Java installation
+
+```python
+>>> from scyjava import config, jimport
+>>> config.set_java_constraints(fetch=True, vendor='zulu', version='17')
+>>> System = jimport('java.lang.System')
+cjdk: Installing JDK zulu:17.0.15 to /home/chuckles/.cache/cjdk
+Download 100% of 189.4 MiB |##########| Elapsed Time: 0:00:02 Time:  0:00:02
+Extract | |                 #                    | 714 Elapsed Time: 0:00:01
+cjdk: Installing Maven to /home/chuckles/.cache/cjdk
+Download 100% of   8.7 MiB |##########| Elapsed Time: 0:00:00 Time:  0:00:00
+Extract | |#                                     | 102 Elapsed Time: 0:00:00
+>>> System.getProperty('java.vendor')
+'Azul Systems, Inc.'
+>>> System.getProperty('java.version')
+'17.0.15'
+```
+
 ## Convert between Python and Java data structures
 
 ### Convert Java collections to Python
@@ -135,7 +153,7 @@ AttributeError: 'list' object has no attribute 'stream'
 Traceback (most recent call last):
   File "<stdin>", line 1, in <module>
 TypeError: No matching overloads found for java.util.Set.addAll(set), options are:
-	public abstract boolean java.util.Set.addAll(java.util.Collection)
+        public abstract boolean java.util.Set.addAll(java.util.Collection)
 >>> from scyjava import to_java as p2j
 >>> jset.addAll(p2j(pset))
 True
@@ -216,6 +234,22 @@ FUNCTIONS
     is_jarray(data: Any) -> bool
         Return whether the given data object is a Java array.
 
+    is_jboolean(the_type: type) -> bool
+
+    is_jbyte(the_type: type) -> bool
+
+    is_jcharacter(the_type: type) -> bool
+
+    is_jdouble(the_type: type) -> bool
+
+    is_jfloat(the_type: type) -> bool
+
+    is_jinteger(the_type: type) -> bool
+
+    is_jlong(the_type: type) -> bool
+
+    is_jshort(the_type: type) -> bool
+
     is_jvm_headless() -> bool
         Return true iff Java is running in headless mode.
 
@@ -267,6 +301,12 @@ FUNCTIONS
         You can pass a single integer to make a 1-dimensional array of that length.
         :return: The newly allocated array
 
+    jsource(data)
+        Try to find the source code using SciJava's SourceFinder.
+        :param data:
+            The object or class or fully qualified class name to check for source code.
+        :return: The URL of the java class
+
     jclass(data)
         Obtain a Java class object.
 
@@ -303,6 +343,14 @@ FUNCTIONS
         :param jtype: The Java type, as either a jimported class or as a string.
         :return: True iff the object is an instance of that Java type.
 
+    jreflect(data, aspect: str = "all") -> List[Dict[str, Any]]
+        Use Java reflection to introspect the given Java object,
+        returning a table of its available methods or fields.
+
+        :param data: The object or class or fully qualified class name to inspect.
+        :param aspect: One of: "all", "constructors", "fields", or "methods".
+        :return: List of dicts with keys: "name", "mods", "arguments", and "returns".
+
     jstacktrace(exc) -> str
         Extract the Java-side stack trace from a Java exception.
 

dev-environment.yml

@@ -12,17 +12,17 @@
 #
 # In addition to the dependencies needed for using scyjava, it
 # includes tools for developer-related actions like running
-# automated tests (pytest) and linting the code (black). If you
+# automated tests (pytest) and linting the code (ruff). If you
 # want an environment without these tools, use environment.yml.
 name: scyjava-dev
 channels:
   - conda-forge
 dependencies:
-  - python >= 3.9
+  - python = 3.9
   # Project dependencies
   - jpype1 >= 1.3.0
   - jgo
-  - openjdk >= 8, < 12
+  - cjdk
   # Test dependencies
   - numpy
   - pandas
@@ -37,6 +37,5 @@ dependencies:
   # Project from source
   - pip
   - pip:
-    - cjdk
     - git+https://github.com/ninia/jep.git@cfca63f8b3398daa6d2685428660dc4b2bfab67d
     - -e .

environment.yml

@@ -12,7 +12,7 @@
 #
 # It includes the dependencies needed for using scyjava, but not tools
 # for developer-related actions like running automated tests (pytest),
-# linting the code (black), and generating the API documentation (sphinx).
+# linting the code (ruff), and generating the API documentation (sphinx).
 # If you want an environment including these tools, use dev-environment.yml.
 
 name: scyjava
@@ -23,7 +23,7 @@ dependencies:
   # Project dependencies
   - jpype1 >= 1.3.0
   - jgo
-  - openjdk >= 8
+  - cjdk
   # Project from source
   - pip
   - pip:

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "scyjava"
-version = "1.11.0.dev0"
+version = "1.12.1.dev0"
 description = "Supercharged Java access from Python"
 license = "Unlicense"
 authors = [{name = "SciJava developers", email = "ctrueden@wisc.edu"}]

src/scyjava/__init__.py

@@ -40,6 +40,22 @@
     +++oo*OO######O**oo+++++oo*OO######O**oo+++++oo*OO######O**oo+++
     +++oo*OO######OO*oo+++++oo*OO######OO*oo+++++oo*OO######OO*oo+++
 
+Bootstrap a Java installation:
+
+    >>> from scyjava import config, jimport
+    >>> config.set_java_constraints(fetch=True, vendor='zulu', version='17')
+    >>> System = jimport('java.lang.System')
+    cjdk: Installing JDK zulu:17.0.15 to /home/chuckles/.cache/cjdk
+    Download 100% of 189.4 MiB |##########| Elapsed Time: 0:00:02 Time:  0:00:02
+    Extract | |                 #                    | 714 Elapsed Time: 0:00:01
+    cjdk: Installing Maven to /home/chuckles/.cache/cjdk
+    Download 100% of   8.7 MiB |##########| Elapsed Time: 0:00:00 Time:  0:00:00
+    Extract | |#                                     | 102 Elapsed Time: 0:00:00
+    >>> System.getProperty('java.vendor')
+    'Azul Systems, Inc.'
+    >>> System.getProperty('java.version')
+    '17.0.15'
+
 Convert Java collections to Python:
 
     >>> from scyjava import jimport
@@ -71,6 +87,7 @@
 from functools import lru_cache
 from typing import Any, Callable, Dict
 
+from . import config, inspect
 from ._arrays import is_arraylike, is_memoryarraylike, is_xarraylike
 from ._convert import (
     Converter,
@@ -91,6 +108,10 @@
     to_java,
     to_python,
 )
+from ._introspect import (
+    jreflect,
+    jsource,
+)
 from ._jvm import (  # noqa: F401
     available_processors,
     gc,

src/scyjava/_cjdk_fetch.py

@@ -1,3 +1,7 @@
+"""
+Utility functions for fetching JDK/JRE and Maven.
+"""
+
 from __future__ import annotations
 
 import logging
@@ -9,21 +13,23 @@
 import cjdk
 import jpype
 
+import scyjava.config
+
 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 ensure_jvm_available() -> None:
     """Ensure that the JVM is available and Maven is installed."""
-    if not is_jvm_available():
+    fetch = scyjava.config.get_fetch_java()
+    if fetch == "never":
+        # Not allowed to use cjdk.
+        return
+    if fetch == "always" or not is_jvm_available():
         cjdk_fetch_java()
-    if not shutil.which("mvn"):
+    if fetch == "always" or not shutil.which("mvn"):
         cjdk_fetch_maven()
 
 
@@ -47,27 +53,27 @@ def _silent_check_output(*args, **kwargs):
     return True
 
 
-def cjdk_fetch_java(vendor: str = "", version: str = "") -> None:
+def cjdk_fetch_java(vendor: str | None = None, version: str | None = None) -> None:
     """Fetch java using cjdk and add it to the PATH."""
-    if not vendor:
-        vendor = os.getenv("JAVA_VENDOR", _DEFAULT_JAVA_VENDOR)
-        version = os.getenv("JAVA_VERSION", _DEFAULT_JAVA_VERSION)
+    if vendor is None:
+        vendor = scyjava.config.get_java_vendor()
+    if version is None:
+        version = scyjava.config.get_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)
+    _logger.info(f"Fetching {vendor}:{version} using cjdk...")
+    java_home = cjdk.java_home(vendor=vendor, version=version)
+    _logger.debug(f"java_home -> {java_home}")
+    _add_to_path(str(java_home / "bin"), front=True)
+    os.environ["JAVA_HOME"] = str(java_home)
 
 
 def cjdk_fetch_maven(url: str = "", sha: str = "") -> None:
     """Fetch Maven using cjdk and add it to the PATH."""
-    # if url was passed as an argument, or env_var, use it with provided sha
+    # if url was passed as an argument, 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
+    if not url:
+        url = scyjava.config.get_maven_url()
+        sha = scyjava.config.get_maven_sha()
 
     # fix urls to have proper prefix for cjdk
     if url.startswith("http"):
@@ -88,7 +94,9 @@ def cjdk_fetch_maven(url: str = "", sha: str = "") -> None:
             )
         kwargs = {sha_lengths[sha_len]: sha}
 
+    _logger.info("Fetching Maven using cjdk...")
     maven_dir = cjdk.cache_package("Maven", url, **kwargs)
+    _logger.debug(f"maven_dir -> {maven_dir}")
     if maven_bin := next(maven_dir.rglob("apache-maven-*/**/mvn"), None):
         _add_to_path(maven_bin.parent, front=True)
     else:  # pragma: no cover