Java API Reference

Types

Where possible types are mapped directly from Python to Java.

Python type	Java type
int	int/Integer - 32 bit signed
str	String (unicode only)
None	null
bool	boolean/Boolean
dict	Map <Object, Object>
list	List <Object>

Note that tuples are mutable and treated as lists.

Your added methods can return types other than the above without error. However there will be type errors if you try to perform operations on them (eg use them as an if expression or add them).

Adding methods

You can make methods available to the Python by calling MiniPython.addModule.

class timeinfo {
   // can't be seen from Python because it is not public
   private void not_exposed() {}

   // using types from above
   public boolean isdst() { return false; }
   public int day_of_week(int year, int month, int day) {  return 2; }
   // Java's type erasure doesn't make the Integer particularly meaningful
   public int sum_all(List<Integer> items) { return 17; }

   // You can use other types
   public Widget get_widget() { return new Widget(); }
   public void show_widget(Widget w, boolean show) { if(show) w.show(); else w.hide(); }

   // varargs is supported
   public String printf(String fmt, Object ...items) { return String.format(fmt, items); }
}

// register it as a module named "example"
MiniPython mp=new MiniPython();
mp.addModule("example", new timeinfo());

You can then call these from Python:

print example.isdst()
print example.sum_all([1, 2, 3, 4])
w=example.get_widget()
example.show_widget(w, True)

Exposure

Only methods that have been declared public will be available. Additionally the method has to be implemented directly in the class. For example toString is not available in the above example as it is implemented in a parent class.

If you have multiple methods with the same name, declared public and implemented directly in the class (eg taking different numbers of arguments) then the one to be used is picked at random. No attempt is made to try and select a method based on number or type of arguments.

No attempt is made to convert method parameters. For example if a method takes a boolean and an int is provided then the int will not be converted to a boolean and there will be an exception.

Errors

If your code encounters an error (for example one of the list items not being an integer in the sum_all method above) then you should call MiniPython.signalError. Note that it will throw ExecutionError after performing internal bookkeeping (eg tracking line numbers) and not return.

class MiniPython

MiniPython

(javadoc) Encapsulates running a Python syntax file.

The source should have been transformed using jmp-compile. The class cannot be used concurrently. There is no shared state between instances.

void addModule(String name, Object object)

Makes methods on the methods Object available to the Python

Param name:Module name in the Python environment Param object:Object to introspect looking for methods

See also

Adding methods

Object callMethod(String name, Object args)

Calls a method in Python and returns the result

Param name:Global method name Param args:Variable list of arguments that it takes Raises ExecutionError:  On any issues encountered

void clear()

Removes all internal state.

This ensures that garbage collection is easier. You can reuse this instance by calling addModule to reregister modules and setCode to run new code.

void setClient(Client client)

Callbacks to use for specific behaviour

Param client:Replaces existing client with this one

void setCode(InputStream stream)

Reads and executes code from the supplied stream

The stream provided must satisfy reads completely (eg if 27 bytes is asked for then that number should be returned in the read() call unless end of file is reached.)

Param stream:The stream is not closed and you can have additional content after the jmp. Raises IOException:  Passed on from read() calls on the stream Raises EOFException:  When the stream is truncated Raises ExecutionError:  Any issues from executing the code

void signalError(String exctype, String message, Throwable cause)

Call this method when your callbacks need to halt execution due to an error

This method will do the internal bookkeeping necessary in order to provide diagnostics to the original caller and then throw an ExecutionError which you should not catch.

Param exctype:Best practise is to use the name of a Python exception (eg “TypeError”) Param message:Text describing the error. Param cause:The underlying reason why this exception is being caused Raises ExecutionError:  Always thrown

String toPyReprString(Object o)

Same as toPyString except strings are quoted and backslash escaped. If you emit an error message this is preferable as it makes it clear a value is a string.

Param o:Object to stringify. Can be null.

String toPyString(Object o)

Returns a string representing the object using Python nomenclature where possible

For example null is returned as None, true as True etc. Container types like dict/Map and list/List will include the items.

Param o:Object to stringify. Can be null.

String toPyTypeString(Object o)

Returns a string representing the type of the object using Python nomenclature where possible

For example null is returned as NoneType, true as bool, Map as dict etc. You can also pass in Class objects as well as instances. Note that primitives (eg int) and the corresponding boxed type (eg Integer) will both be returned as the same string (int in this case).

Param o:Object whose type to stringify, or a Class or null

interface MiniPython.Client

Client

(javadoc) Provide platform behaviour

void onError(ExecutionError error)

Called whenever there is an ExecutionError.

This provides one spot where you can perform logging and other diagnostics.

Param error:The instance that is about to be thrown

void print(String s)

Request to print a string

Param s:String to print. May or may not contain a trailing newline depending on code Raises ExecutionError:  Throw this if you experience any issues

class MiniPython.ExecutionError

ExecutionError

(javadoc) Encapsulates what would be an Exception in Python.

Do not instantiate one directly - call signalError instead.

String getType()

Returns the type of the error.

This typically corresponds to a Python exception (eg TypeError or IndexError)

int linenumber()

Returns the line number which was being executed when the error happened.

If you omitted line numbers then -1 is returned.

int pc()

Returns program counter when error occurred.

Note that due to internal implementation details this is the next instruction to be executed, not the currently executing one.

String toDetailedString()

Returns more detailed than toString (eg includes linenumber and pc). In the future it may also include a stack trace and local variables.

String toString()

Returns “type: message” for the error