8000 README: update API documentation for 1.8.0 release · scijava/scyjava@dc7bce7 · GitHub
[go: up one dir, main page]
Skip to content
< 8000 script crossorigin="anonymous" defer="defer" type="application/javascript" src="https://github.githubassets.com/assets/vendors-node_modules_github_remote-form_dist_index_js-node_modules_delegated-events_dist_inde-94fd67-e789af5a4655.js">

Commit dc7bce7

Browse files
ctruedenctrueden
committed
README: update API documentation for 1.8.0 release
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.
1 parent 23a713f commit dc7bce7

File tree

1 file changed

+63
-28
lines changed

1 file changed

+63
-28
lines changed

‎README.md

Lines changed: 63 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -150,21 +150,15 @@ True
150150
>>> help(scyjava)
151151
...
152152
FUNCTIONS
153-
add_java_converter(converter: scyjava.Converter)
154-
Adds a converter to the list used by to_java
153+
add_java_converter(converter: scyjava._convert.Converter) -> None
154+
Add a converter to the list used by to_java.
155155
:param converter: A Converter going from python to java
156156

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

161-
constant(func: Callable[[], Any], cache=True) -> Callable[[], Any]
162-
Turns a function into a property of this module
163-
Functions decorated with this property must have a
164-
leading underscore!
165-
:param func: The function to turn into a property
166-
167-
get_version(java_class_or_python_package)
161+
get_version(java_class_or_python_package) -> str
168162
Return the version of a Java class or Python package.
169163

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

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

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

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

188-
is_awt_initialized()
182+
is_awt_initialized() -> bool
189183
Return true iff the AWT subsystem has been initialized.
190184

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

198-
is_jvm_headless()
192+
is_jarray(data) -> bool
193+
Return whether the given data object is a Java array.
194+
195+
is_jvm_headless() -> bool
199196
Return true iff Java is running in headless mode.
200197

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

203-
is_memoryarraylike(arr)
200+
is_memoryarraylike(arr: Any) -> bool
204201
Return True iff the object is memoryarraylike:
205202
an arraylike object whose .data type is memoryview.
206203

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

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

@@ -216,18 +213,18 @@ FUNCTIONS
216213

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

219-
is_xarraylike(xarr)
216+
is_xarraylike(xarr: Any) -> bool
220217
Return True iff the object is xarraylike:
221218
possessing .values, .dims, and .coords attributes,
222219
and whose .values are arraylike.
223220

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

227-
isjava(data)
224+
isjava(data) -> bool
228225
Return whether the given data object is a Java object.
229226

230-
jarray(kind, lengths)
227+
jarray(kind, lengths: Sequence)
231228
Create a new n-dimensional Java array.
232229

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

261-
jimport(class_name)
258+
jimport(class_name: str)
262259
Import a class from Java to Python.
263260

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

268-
jstacktrace(exc)
265+
jinstance(obj, jtype) -> bool
266+
Test if the given object is an instance of a particular Java type.
267+
268+
:param obj: The object to check.
269+
:param jtype: The Java type, as either a jimported class or as a string.
270+
:returns: True iff the object is an instance of that Java type.
271+
272+
jstacktrace(exc) -> str
269273
Extract the Java-side stack trace from a Java exception.
270274

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

284-
jvm_started()
288+
jvm_started() -> bool
285289
Return true iff a Java virtual machine (JVM) has been started.
286290

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

310-
shutdown_jvm()
314+
shutdown_jvm() -> None
311315
Shutdown the JVM.
312316

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

329-
start_jvm(options=None)
333+
start_jvm(options=None) -> None
330334
Explicitly connect to the Java virtual machine (JVM). Only one JVM can
331335
be active; does nothing if the JVM has already been started. Calling
332336
this function directly is typically not necessary, because the first
@@ -336,7 +340,7 @@ FUNCTIONS
336340
:param options: List of options to pass to the JVM. For example:
337341
['-Djava.awt.headless=true', '-Xmx4g']
338342

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

342346
Supported types include:
@@ -348,7 +352,38 @@ FUNCTIONS
348352
* set -> LinkedHashSet
349353
* list -> ArrayList
350354

355+
There is typically one single destination conversion type and value that
356+
makes sense. For example, Python str always converts to java.lang.String.
357+
But in some cases, there are multiple options that can be controlled by
358+
passing key/value pairs as hints. The base scyjava library includes:
359+
360+
* int + type='byte' -> Byte
361+
* int + type='short' -> Short
362+
* int + type='int' -> Integer
363+
* int + type='long' -> Long
364+
* int + type='bigint' -> BigInteger
365+
* float + type='float' -> Float
366+
* float + type='double' -> Double
367+
* float + type='bigdec' -> BigDecimal
368+
369+
But the scyjava conversion framework is extensible and other
370+
packages may introduce converters supporting additional hints.
371+
372+
In the absence of a hint, scyjava makes a best effort to use a sensible
373+
destination type and value:
374+
375+
* int values in [-2**31, 2**31-1] convert to Integer
376+
* int values in [-2**63, 2**63-1] but outside int range convert to Long
377+
* int values outside Java long range convert to BigInteger
378+
* conversion of int to Byte or Short must be requested via a hint
379+
* float values in Float range convert to Float
380+
* float inf, -inf, and nan convert to Float
381+
* float values in Double range but outside float range convert to Double
382+
* float values outside double range convert to BigDecimal
383+
351384
:param obj: The Python object to convert.
385+
:param hints: An optional dictionary of hints, to help scyjava
386+
make decisions about how to do the conversion.
352387
:returns: A corresponding Java object with the same contents.
353388
:raises TypeError: if the argument is not one of the aforementioned types.
354389

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

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

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

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

0 commit comments

Comments
 (0)
0