py4j.protocol
— Py4J Protocol¶The py4j.protocol
module defines most of the types, functions, and
characters used in the Py4J protocol. It does not need to be explicitly used by
clients of Py4J because it is automatically loaded by the java_gateway
module and the java_collections
module.
Exception raised when a problem occurs with Py4J.
Exception raised when an exception occurs in the client code.
The exception instance that was thrown on the Java side can be accessed with Py4JJavaError.java_exception.
str(py4j_java_error) returns the error message and the stack trace available on the Java side (similar to printStackTrace()).
Note that str(py4j_java_error) in Python 2 might not automatically handle a non-ascii unicode string but throw an error if the exception contains it.
Exception raised when a network error occurs with Py4J.
Exception raised when Py4J cannot authenticate a connection.
The following functions can be used to extend Py4J (e.g., to create new commands):
Replaces new line characters by a backslash followed by a n.
Backslashes are also escaped by another backslash.
original – the string to escape
an escaped string
Replaces escaped characters by unescaped characters.
For example, double backslashes are replaced by a single backslash.
The behavior for improperly formatted strings is undefined and can change.
escaped – the escaped string
the original string
Converts a Python object into a string representation respecting the Py4J protocol.
For example, the integer 1 is converted to u”i1”
parameter – the object to convert
the string representing the command part
Converts an answer received from the Java gateway into a Python object.
For example, string representation of integers are converted to Python integer, string representation of objects are converted to JavaObject instances, etc.
answer – the string returned by the Java gateway
gateway_client – the gateway client used to communicate with the Java Gateway. Only necessary if the answer is a reference (e.g., object, list, map)
target_id – the name of the object from which the answer comes from (e.g., object1 in object1.hello()). Optional.
name – the name of the member from which the answer comes from (e.g., hello in object1.hello()). Optional.
Registers an output converter to the list of global output converters.
An output converter transforms the output of the Java side to an instance
on the Python side. For example, you could transform a java.util.ArrayList
to a Python list. See py4j.java_collections
for examples.
output_type – A Py4J type of a return object (e.g., MAP_TYPE, BOOLEAN_TYPE).
converter – A function that takes an object_id and a gateway_client as parameter and that returns a Python object (like a bool or a JavaObject instance).
Registers an input converter to the list of global input converters.
An input converter transforms the input of the Python side to an instance
on the Java side. For example, you could transform a Python list into a
java.util.ArrayList on the Java side. See py4j.java_collections
for
examples.
When initialized with auto_convert=True, a JavaGateway
will use the input converters on any
parameter that is not a JavaObject
or basestring instance.
converter – A converter that declares the methods can_convert(object) and convert(object,gateway_client).
prepend – Put at the beginning of the input converters list