refactor: rename dynamic_import to setup_java_imports and update usag…

…e in stubs
scijava · tlambert03 · Apr 23, 2025 · Apr 23, 2025 · Apr 23, 2025 · Apr 23, 2025
commit 2cb4836c370a678b307849891300d28a9777b6e1
diff --git a/src/scyjava/_stubs/__init__.py b/src/scyjava/_stubs/__init__.py
@@ -1,4 +1,4 @@
-from ._dynamic_import import dynamic_import
+from ._dynamic_import import setup_java_imports
 from ._genstubs import generate_stubs
 
-__all__ = ["dynamic_import", "generate_stubs"]
+__all__ = ["setup_java_imports", "generate_stubs"]
diff --git a/src/scyjava/_stubs/_dynamic_import.py b/src/scyjava/_stubs/_dynamic_import.py
@@ -4,12 +4,51 @@
 from typing import Any, Callable, Sequence
 
 
-def dynamic_import(
+def setup_java_imports(
     module_name: str,
     module_file: str,
     endpoints: Sequence[str] = (),
     base_prefix: str = "",
 ) -> tuple[list[str], Callable[[str], Any]]:
+    """Setup a module to dynamically import Java class names.
+
+    This function creates a `__getattr__` function that, when called, will dynamically
+    import the requested class from the Java namespace corresponding to this module.
+
+    :param module_name: The dotted name/identifier of the module that is calling this
+        function (usually `__name__` in the calling module).
+    :param module_file: The path to the module file (usually `__file__` in the calling
+        module).
+    :param endpoints: A list of Java endpoints to add to the scyjava configuration.
+    :param base_prefix: The base prefix for the Java package name. This is used when
+        determining the Java class path for the requested class. The java class path
+        will be truncated to only the part including the base_prefix and after.  This
+        makes it possible to embed a module in a subpackage (like `scyjava.types`) and
+        still have the correct Java class path.
+    :return: A 2-tuple containing:
+        - A list of all classes in the module (as defined in the stub file), to be
+            assigned to `__all__`.
+        - A callable that takes a class name and returns a proxy for the Java class.
+            This callable should be assigned to `__getattr__` in the calling module.
+            The proxy object, when called, will start the JVM, import the Java class,
+            and return an instance of the class.  The JVM will *only* be started when
+            the object is called.
+
+    Example:
+    If the module calling this function is named `scyjava.types.org.scijava.parsington`,
+    then it should invoke this function as:
+
+    .. code-block:: python
+
+        from scyjava._stubs import setup_java_imports
+
+        __all__, __getattr__ = setup_java_imports(
+            __name__,
+            __file__,
+            endpoints=["org.scijava:parsington:3.1.0"],
+            base_prefix="org"
+        )
+    """
     import scyjava
     import scyjava.config
 

diff --git a/src/scyjava/_stubs/_genstubs.py b/src/scyjava/_stubs/_genstubs.py
@@ -15,7 +15,6 @@
 
 import scyjava
 import scyjava.config
-import stubgenj
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -69,6 +68,14 @@ def generate_stubs(
         the `__init__.pyi` for any given module will be whatever whatever the *last*
         stub generator wrote to it (and therefore inaccurate).
     """
+    try:
+        import stubgenj
+    except ImportError as e:
+        raise ImportError(
+            "stubgenj is not installed, but is required to generate java stubs. "
+            "Please install it with `pip/conda install stubgenj`."
+        ) from e
+
     import jpype
 
     startJVM = jpype.startJVM
@@ -145,9 +152,9 @@ def _patched_start(*args: Any, **kwargs: Any) -> None:
 # it creates a __getattr__ function that will dynamically import
 # the requested class from the Java namespace corresponding to this module.
 # see scyjava._stubs for implementation details.
-from scyjava._stubs import dynamic_import
+from scyjava._stubs import setup_java_imports
 
-__all__, __getattr__ = dynamic_import(
+__all__, __getattr__ = setup_java_imports(
     __name__,
     __file__,
     endpoints={endpoints},