On This Page

Previous topic

4.1. py4j.java_gateway — Py4J Main API

Next topic

4.3. py4j.java_collections — Py4J Collections API

This Page

4.2. 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.2.1. Py4JError

class py4j.protocol.Py4JError

Exception thrown when a problem occurs with Py4J.

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

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.

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)

Registers an input converter to the list of global input converters.

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

Questions/Feedback?

blog comments powered by Disqus