4.4. py4j.java_collections — Py4J Collections API

The py4j.java_collections module maps Python collection classes with Java collection classes. These classes should practically never be directly instantiated by users: they are automatically used when receiving, for example, a Java list.

4.4.1. JavaIterator

class py4j.java_collections.JavaIterator(target_id, gateway_client)

Maps a Python list iterator to a Java list iterator.

The JavaIterator follows the Python iterator protocol and raises a StopIteration error when the iterator can no longer iterate.

Parameters:

• target_id – the identifier of the object on the JVM side. Given by the JVM.

• gateway_client – the gateway client used to communicate with the JVM.

next()

This next method wraps the next method in Java iterators.

The Iterator.next() method is called and if an exception occur (e.g., NoSuchElementException), a StopIteration exception is raised.

4.4.2. JavaList

class py4j.java_collections.JavaList(target_id, gateway_client)

Maps a Python list to a Java list.

All operations possible on a Python list are implemented. For example, slicing (e.g., list[1:3]) will create a copy of the list on the JVM. Slicing is thus not equivalent to subList(), because a modification to a slice such as the addition of a new element will not affect the original list.

Parameters:

• target_id – the identifier of the object on the JVM side. Given by the JVM.

• gateway_client – the gateway client used to communicate with the JVM.

append(value)

S.append(value) – append value to the end of the sequence

count(value) → integer -- return number of occurrences of value

extend(other_list)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(key, value)

S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

sort()

4.4.3. JavaMap

class py4j.java_collections.JavaMap(target_id, gateway_client)

Maps a Python Dictionary to a Java Map.

All operations possible on a Python dict are implemented.

Parameters:

• target_id – the identifier of the object on the JVM side. Given by the JVM.

• gateway_client – the gateway client used to communicate with the JVM.

4.4.4. JavaSet

class py4j.java_collections.JavaSet(target_id, gateway_client)

Maps a Python Set to a Java Set.

All operations possible on a Python set are implemented.

Parameters:

• target_id – the identifier of the object on the JVM side. Given by the JVM.

• gateway_client – the gateway client used to communicate with the JVM.

add(value)

Add an element.

clear()

This is slow (creates N new iterators!) but effective.

discard(value)

Remove an element. Do not raise an exception if absent.

remove(value)

Remove an element. If not a member, raise a KeyError.

4.4.5. JavaArray

class py4j.java_collections.JavaArray(target_id, gateway_client)

Maps a Java Array to a Semi-Mutable Sequence: elements inside the sequence can be modified, but the length of the sequence cannot change.

The backing collection is a Sequence and not a Python array because these arrays only accept primitives whereas Java arrays work for any types.

Parameters:

• target_id – the identifier of the object on the JVM side. Given by the JVM.

• gateway_client – the gateway client used to communicate with the JVM.