pysnt.java_utils module#

Java utilities for PySNT.

This module handles Java/OpenJDK installation and configuration, as well as Java class introspection utilities.

The reflection functions use scyjava’s reflection tools: - inspect(): Uses jreflect for detailed class inspection - get_methods(): Uses jreflect to retrieve method information - get_fields(): Uses jreflect to retrieve field information - is_instance_of(): Uses jinstance for type checking - reflect_java_object(): Direct wrapper around jreflect

check_java_installation() → Dict[str, Any][source]#

Check current Java installation status.

Returns:

Dictionary with Java installation information: - ‘available’: bool - Whether Java is available - ‘version’: int or None - Java version number - ‘version_string’: str or None - Full version string - ‘java_home’: str or None - JAVA_HOME path - ‘executable’: str or None - Java executable path - ‘vendor’: str or None - Java vendor - ‘meets_requirements’: bool - Whether version meets requirements

Return type:

Dict[str, Any]

ensure_java_available(required_version: int = REQUIRED_JAVA_VERSION, auto_install: bool = True) → bool[source]#

Ensure Java is available with required version.

Parameters:

  • required_version (int, default 21) – Required Java version

  • auto_install (bool, default True) – Whether to automatically install Java if not available

Returns:

True if Java is available with required version

Return type:

bool

install_openjdk(version: int = REQUIRED_JAVA_VERSION) → bool[source]#

Install OpenJDK using install-jdk package.

Parameters:

version (int, default 21) – Java version to install

Returns:

True if installation was successful

Return type:

bool

print_java_status()[source]#

Print detailed Java installation status.

setup_java_environment() → bool[source]#

Interactive Java environment setup.

Returns:

True if Java is properly set up

Return type:

bool

inspect(class_or_object: str | Any, keyword: str = '', methods: bool = True, fields: bool = True, constructors: bool = False, static_only: bool = False, case_sensitive: bool = False, max_results: int = 50) → None[source]#

Inspect a Java class or object, listing methods and fields matching a keyword.

This function uses scyjava’s jreflect to introspect classes and display their public methods and fields. Useful for exploring SNT classes and discovering available functionality.

Parameters:

  • class_or_object (str or Java object) – Either a string class name (e.g., ‘TreeStatistics’) or a Java class/object

  • keyword (str, default "") – Filter results to only show items containing this keyword (case-insensitive by default)

  • methods (bool, default True) – Whether to show methods

  • fields (bool, default True) – Whether to show fields

  • constructors (bool, default False) – Whether to show constructors

  • static_only (bool, default False) – Whether to show only static members

  • case_sensitive (bool, default False) – Whether keyword matching should be case-sensitive

  • max_results (int, default 50) – Maximum number of results to display per category

Examples

>>> # Inspect TreeStatistics class
>>> inspect('TreeStatistics')

>>> # Look for methods containing 'length'
>>> inspect('TreeStatistics', 'length', fields=False)

>>> # Inspect an instance
>>> from pysnt.analysis import TreeStatistics
>>> stats = TreeStatistics()
>>> inspect(stats, 'get')

>>> # Show only static methods
>>> inspect('TreeStatistics', static_only=True, fields=False)
get_methods(class_or_object: str | Any, static_only: bool = False, include_inherited: bool = True) → list[source]#

Retrieve all public methods from a Java class or object using scyjava.jreflect.

Parameters:

  • class_or_object (str or Java object) – Either a string class name or a Java class/object

  • static_only (bool, default False) – Whether to return only static methods

  • include_inherited (bool, default True) – Whether to include inherited methods (from Object class excluded)

Returns:

List of dictionaries containing method information: - ‘name’: method name - ‘params’: list of parameter type names - ‘return_type’: return type name - ‘is_static’: whether method is static - ‘signature’: full method signature string

Return type:

list

Examples

>>> methods = get_methods('TreeStatistics')
>>> for method in methods:
...     print(f"{method['name']}({', '.join(method['params'])}) -> {method['return_type']}")
get_fields(class_or_object: str | Any, static_only: bool = False) → list[source]#

Retrieve all public fields from a Java class or object using scyjava.jreflect.

Parameters:

  • class_or_object (str or Java object) – Either a string class name or a Java class/object

  • static_only (bool, default False) – Whether to return only static fields

Returns:

List of dictionaries containing field information: - ‘name’: field name - ‘type’: field type name - ‘is_static’: whether field is static - ‘is_final’: whether field is final - ‘signature’: full field signature string

Return type:

list

Examples

>>> fields = get_fields('TreeStatistics')
>>> for field in fields:
...     print(f"{field['name']}: {field['type']}")
get_inner_classes(class_or_object: str | Any) → list[source]#

Retrieve all public inner classes from a Java class.

Note: This function uses traditional Java reflection as scyjava.jreflect doesn’t currently provide inner class information.

Parameters:

class_or_object (str or Java object) – Either a string class name or a Java class/object

Returns:

List of dictionaries containing inner class information: - ‘name’: simple class name - ‘full_name’: full qualified class name - ‘is_static’: whether the inner class is static - ‘is_interface’: whether it’s an interface - ‘is_enum’: whether it’s an enum - ‘signature’: descriptive signature string

Return type:

list

Examples

>>> inner_classes = get_inner_classes('CircularModels')
>>> for cls in inner_classes:
...     print(f"{cls['name']}: {cls['full_name']}")
is_instance_of(obj: Any, jtype: str | Any) → bool[source]#

Test if the given object is an instance of a particular Java type using scyjava.jinstance.

This is a wrapper around scyjava’s jinstance function that provides better error handling and logging for the PySNT context.

Parameters:

  • obj (Any) – The object to check

  • jtype (str or Java class) – The Java type, as either a jimported class or as a string

Returns:

True if the object is an instance of that Java type, False otherwise

Return type:

bool

Examples

>>> from pysnt.analysis import TreeStatistics
>>> stats = TreeStatistics()
>>> is_instance_of(stats, 'sc.fiji.snt.analysis.TreeStatistics')
True

>>> # Using jimported class
>>> TreeStats = scyjava.jimport('sc.fiji.snt.analysis.TreeStatistics')
>>> is_instance_of(stats, TreeStats)
True
reflect_java_object(data: Any, aspect: str = 'all') → List[Dict[str, Any]][source]#

Use Java reflection to introspect the given Java object using scyjava.jreflect.

This is a wrapper around scyjava’s jreflect function that provides better error handling and logging for the PySNT context.

Parameters:

  • data (Any) – The object or class or fully qualified class name to inspect

  • aspect (str, default "all") – One of: “all”, “constructors”, “fields”, or “methods”

Returns:

List of dicts with keys: “name”, “mods”, “arguments”, and “returns”

Return type:

List[Dict[str, Any]]

Examples

>>> from pysnt.analysis import TreeStatistics
>>> methods = reflect_java_object(TreeStatistics, "methods")
>>> for method in methods:
...     print(f"{method['name']}: {method.get('returns', 'void')}")

>>> # Get all reflection info
>>> all_info = reflect_java_object('sc.fiji.snt.analysis.TreeStatistics')
find_members(class_or_object: str | Any, keyword: str, include_methods: bool = True, include_fields: bool = True, include_inner_classes: bool = True, static_only: bool = False, case_sensitive: bool = False) → Dict[str, list][source]#

Find methods, fields, and inner classes matching a keyword in a Java class or object.

This function now uses scyjava.jreflect for improved performance and consistency.

Parameters:

  • class_or_object (str or Java object) – Either a string class name or a Java class/object

  • keyword (str) – Keyword to search for in method, field, and inner class names

  • include_methods (bool, default True) – Whether to search methods

  • include_fields (bool, default True) – Whether to search fields

  • include_inner_classes (bool, default True) – Whether to search inner classes

  • static_only (bool, default False) – Whether to search only static members

  • case_sensitive (bool, default False) – Whether keyword matching should be case-sensitive

Returns:

Dictionary with ‘methods’, ‘fields’, and ‘inner_classes’ keys containing matching members. Each member is a dictionary with detailed information.

Return type:

Dict[str, list]

Examples

>>> # Find all members containing 'length'
>>> results = find_members('TreeStatistics', 'length')
>>> print(f"Found {len(results['methods'])} methods and {len(results['fields'])} fields")

>>> # Find inner classes containing 'Fit'
>>> results = find_members('CircularModels', 'Fit')
>>> print(f"Found {len(results['inner_classes'])} inner classes")

>>> # Find only static methods containing 'get'
>>> results = find_members('TreeStatistics', 'get',
...                       include_fields=False, static_only=True)
discover_java_classes(package_name: str, known_classes: List[str] | None = None, include_abstract: bool = False, include_interfaces: bool = False) → List[str][source]#

Discover all public classes in a Java package.

This utility function dynamically discovers classes from Java packages using a multi-step approach:

  1. First attempts JAR file scanning for .class files

  2. If no known_classes provided, scans pysnt module __init__.py files for CURATED_CLASSES and EXTENDED_CLASSES lists

  3. Tests each candidate class for existence and visibility

The dynamic scanning approach finds significantly more classes than hardcoded lists and automatically stays up-to-date with module definitions.

Parameters:

  • package_name (str) – Full Java package name (e.g., ‘sc.fiji.snt.analysis’)

  • known_classes (List[str], optional) – List of known class names to test. If None, scans pysnt modules dynamically.

  • include_abstract (bool, default False) – Whether to include abstract classes

  • include_interfaces (bool, default False) – Whether to include interfaces

Returns:

List of discovered public class names

Return type:

List[str]

Examples

>>> # Discover analysis classes (scans pysnt.analysis modules)
>>> classes = discover_java_classes('sc.fiji.snt.analysis')
>>>
>>> # Discover with explicit class list
>>> known = ['TreeStatistics', 'ConvexHull']
>>> classes = discover_java_classes('sc.fiji.snt.analysis', known)

Notes

The dynamic scanning finds classes from: - CURATED_CLASSES lists in matching pysnt modules - EXTENDED_CLASSES lists in matching pysnt modules - All submodules of the matching package

For ‘sc.fiji.snt.analysis’, this scans: - src/pysnt/analysis/__init__.py - src/pysnt/analysis/graph/__init__.py - src/pysnt/analysis/sholl/__init__.py - And other analysis submodules

configure_java_logging() → bool[source]#

Configure Java-side logging based on current PySNT configuration options.

This function reads the current configuration settings and applies them to various Java logging frameworks to control verbosity.

The configuration is controlled via pysnt.set_option(): - ‘java.logging.level’: Logging level (OFF, ERROR, WARN, INFO, DEBUG, TRACE) - ‘java.logging.jpype.silence’: Whether to silence JPype logging - ‘java.logging.log4j.silence’: Whether to silence Log4j logging - ‘java.logging.slf4j.silence’: Whether to silence SLF4J logging - ‘java.logging.jul.silence’: Whether to silence java.util.logging

Returns:

True if configuration was successful, False otherwise

Return type:

bool

Examples

>>> # Configure logging via options
>>> pysnt.set_option('java.logging.level', 'ERROR')
>>> pysnt.set_option('java.logging.jpype.silence', True)
>>> pysnt.configure_java_logging()
>>>
>>> # Set to INFO level for debugging
>>> pysnt.set_option('java.logging.level', 'INFO')
>>> pysnt.configure_java_logging()
>>>
>>> # Only silence JPype, keep other logging
>>> pysnt.set_option('java.logging.jpype.silence', True)
>>> pysnt.set_option('java.logging.log4j.silence', False)
>>> pysnt.set_option('java.logging.slf4j.silence', False)
>>> pysnt.configure_java_logging()