Py4J - A Bridge between Python and Java

### Navigation

- index
- modules |
- next |
- previous |
- Home |
- Download |
- Doc |
- Blog |
- github |
- About »

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

## 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

### Questions/Feedback?

- Try the FAQ -- It answers many questions.
- Search for information in the archives of the py4j-users mailing list, or post a question.
- If you notice errors with this documentation, open a ticket and let us know. Please, only open a ticket for feedback or improvements on the docs. To get help, use the links above!
- Request professional services to get a custom feature implemented quickly or to receive commercial support.

### Navigation

- index
- modules |
- next |
- previous |
- Home |
- Download |
- Doc |
- Blog |
- github |
- About »