Skip to content

Commit

Permalink
README: update API documentation for 1.8.0 release
Browse files Browse the repository at this point in the history 
Note that this removes the constant decorator method, which does not
yet work outside of scyjava, and is not currently part of __all__.
At some point in future we might make it work (see #40),
at which point we would add it to __all__ and put it back in the README.
  • Loading branch information
@ctrueden
ctrueden committed Nov 3, 2022
1 parent 23a713f commit dc7bce7
Showing 1 changed file with 63 additions and 28 deletions.
91 changes: 63 additions & 28 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -150,21 +150,15 @@ True
>>> help(scyjava)
...
FUNCTIONS
add_java_converter(converter: scyjava.Converter)
Adds a converter to the list used by to_java
add_java_converter(converter: scyjava._convert.Converter) -> None
Add a converter to the list used by to_java.
:param converter: A Converter going from python to java

add_py_converter(converter: scyjava.Converter)
Adds a converter to the list used by to_python
add_py_converter(converter: scyjava._convert.Converter) -> None
Add a converter to the list used by to_python.
:param converter: A Converter from java to python

constant(func: Callable[[], Any], cache=True) -> Callable[[], Any]
Turns a function into a property of this module
Functions decorated with this property must have a
leading underscore!
:param func: The function to turn into a property

get_version(java_class_or_python_package)
get_version(java_class_or_python_package) -> str
Return the version of a Java class or Python package.

For Python package, uses importlib.metadata.version if available
Expand All @@ -178,14 +172,14 @@ FUNCTIONS

See org.scijava.VersionUtils.getVersion(Class) for further details.

is_arraylike(arr)
is_arraylike(arr: Any) -> bool
Return True iff the object is arraylike: possessing
.shape, .dtype, .__array__, and .ndim attributes.

:param arr: The object to check for arraylike properties
:return: True iff the object is arraylike

is_awt_initialized()
is_awt_initialized() -> bool
Return true iff the AWT subsystem has been initialized.

Java starts up its AWT subsystem automatically and implicitly, as
Expand All @@ -195,19 +189,22 @@ FUNCTIONS
those actions via the jpype.setupGuiEnvironment wrapper function;
see the Troubleshooting section of the scyjava README for details.

is_jvm_headless()
is_jarray(data) -> bool
Return whether the given data object is a Java array.

is_jvm_headless() -> bool
Return true iff Java is running in headless mode.

:raises RuntimeError: If the JVM has not started yet.

is_memoryarraylike(arr)
is_memoryarraylike(arr: Any) -> bool
Return True iff the object is memoryarraylike:
an arraylike object whose .data type is memoryview.

:param arr: The object to check for memoryarraylike properties
:return: True iff the object is memoryarraylike

is_version_at_least(actual_version, minimum_version)
is_version_at_least(actual_version: str, minimum_version: str) -> bool
Return a boolean on a version comparison.
Requires org.scijava:scijava-common on the classpath.

Expand All @@ -216,18 +213,18 @@ FUNCTIONS

See org.scijava.VersionUtils.compare(String, String) for further details.

is_xarraylike(xarr)
is_xarraylike(xarr: Any) -> bool
Return True iff the object is xarraylike:
possessing .values, .dims, and .coords attributes,
and whose .values are arraylike.

:param arr: The object to check for xarraylike properties
:return: True iff the object is xarraylike

isjava(data)
isjava(data) -> bool
Return whether the given data object is a Java object.

jarray(kind, lengths)
jarray(kind, lengths: Sequence)
Create a new n-dimensional Java array.

:param kind: The type of array to create. This can either be a particular
Expand Down Expand Up @@ -258,14 +255,21 @@ FUNCTIONS
:returns: A java.lang.Class object, suitable for use with reflection.
:raises TypeError: if the argument is not one of the aforementioned types.

jimport(class_name)
jimport(class_name: str)
Import a class from Java to Python.

:param class_name: Name of the class to import.
:returns: A pointer to the class, which can be used to
e.g. instantiate objects of that class.

jstacktrace(exc)
jinstance(obj, jtype) -> bool
Test if the given object is an instance of a particular Java type.

:param obj: The object to check.
:param jtype: The Java type, as either a jimported class or as a string.
:returns: True iff the object is an instance of that Java type.

jstacktrace(exc) -> str
Extract the Java-side stack trace from a Java exception.

Example of usage:
Expand All @@ -281,10 +285,10 @@ FUNCTIONS
:returns: A multi-line string containing the stack trace, or empty string
if no stack trace could be extracted.

jvm_started()
jvm_started() -> bool
Return true iff a Java virtual machine (JVM) has been started.

jvm_version()
jvm_version() -> str
Gets the version of the JVM as a tuple,
with each dot-separated digit as one element.
Characters in the version string beyond only
Expand All @@ -307,7 +311,7 @@ FUNCTIONS
JVM in-process. If the version cannot be deduced, a RuntimeError
with the cause is raised.

shutdown_jvm()
shutdown_jvm() -> None
Shutdown the JVM.

This function makes a best effort to clean up Java resources first.
Expand All @@ -326,7 +330,7 @@ FUNCTIONS
Note that if the JVM is not already running, then this function does
nothing! In particular, shutdown hooks are skipped in this situation.

start_jvm(options=None)
start_jvm(options=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
this function directly is typically not necessary, because the first
Expand All @@ -336,7 +340,7 @@ FUNCTIONS
:param options: List of options to pass to the JVM. For example:
['-Djava.awt.headless=true', '-Xmx4g']

to_java(obj: Any) -> Any
to_java(obj: Any, **hints: Dict) -> Any
Recursively convert a Python object to a Java object.

Supported types include:
Expand All @@ -348,7 +352,38 @@ FUNCTIONS
* set -> LinkedHashSet
* list -> ArrayList

There is typically one single destination conversion type and value that
makes sense. For example, Python str always converts to java.lang.String.
But in some cases, there are multiple options that can be controlled by
passing key/value pairs as hints. The base scyjava library includes:

* int + type='byte' -> Byte
* int + type='short' -> Short
* int + type='int' -> Integer
* int + type='long' -> Long
* int + type='bigint' -> BigInteger
* float + type='float' -> Float
* float + type='double' -> Double
* float + type='bigdec' -> BigDecimal

But the scyjava conversion framework is extensible and other
packages may introduce converters supporting additional hints.

In the absence of a hint, scyjava makes a best effort to use a sensible
destination type and value:

* int values in [-2**31, 2**31-1] convert to Integer
* int values in [-2**63, 2**63-1] but outside int range convert to Long
* int values outside Java long range convert to BigInteger
* conversion of int to Byte or Short must be requested via a hint
* float values in Float range convert to Float
* float inf, -inf, and nan convert to Float
* float values in Double range but outside float range convert to Double
* float values outside double range convert to BigDecimal

:param obj: The Python object to convert.
:param hints: An optional dictionary of hints, to help scyjava
make decisions about how to do the conversion.
:returns: A corresponding Java object with the same contents.
:raises TypeError: if the argument is not one of the aforementioned types.

Expand All @@ -374,15 +409,15 @@ FUNCTIONS
:raises TypeError: if the argument is not one of the aforementioned types,
and the gentle flag is not set.

when_jvm_starts(f)
when_jvm_starts(f) -> None
Registers a function to be called when the JVM starts (or immediately).
This is useful to defer construction of Java-dependent data structures
until the JVM is known to be available. If the JVM has already been
started, the function executes immediately.

:param f: Function to invoke when scyjava.start_jvm() is called.

when_jvm_stops(f)
when_jvm_stops(f) -> None
Registers a function to be called just before the JVM shuts down.
This is useful to perform cleanup of Java-dependent data structures.

Expand Down

0 comments on commit dc7bce7

Please sign in to comment.