4.3. 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.

4.3.1. Py4JError

class py4j.protocol.Py4JError(args=None, cause=None)

Exception raised when a problem occurs with Py4J.

4.3.2. Py4JJavaError

class py4j.protocol.Py4JJavaError(msg, java_exception)

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.

4.3.3. Py4JNetworkError

class py4j.protocol.Py4JNetworkError(args=None, cause=None, when=None)

Exception raised when a network error occurs with Py4J.

4.3.4. Py4JAuthenticationError

class py4j.protocol.Py4JAuthenticationError(args=None, cause=None)

Exception raised when Py4J cannot authenticate a connection.

4.3.5. Py4J Protocol Functions

The following functions can be used to extend Py4J (e.g., to create new commands):

py4j.protocol.escape_new_line(original)

Replaces new line characters by a backslash followed by a n.

Backslashes are also escaped by another backslash.

Parameters:

original – the string to escape

Return type:

an escaped string

py4j.protocol.unescape_new_line(escaped)

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.

Parameters:

escaped – the escaped string

Return type:

the original string

py4j.protocol.get_command_part(parameter, python_proxy_pool=None)

Converts a Python object into a string representation respecting the Py4J protocol.

For example, the integer 1 is converted to u”i1”

Parameters:

parameter – the object to convert

Return type:

the string representing the command part

py4j.protocol.get_return_value(answer, gateway_client, target_id=None, name=None)

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.

Parameters:

• 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.

py4j.protocol.register_output_converter(output_type, converter)

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.

Parameters:

• 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).

py4j.protocol.register_input_converter(converter, prepend=False)

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.

Parameters:

• 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