Over a million developers have joined DZone.

Getting Started With Hazelcast Python Client 0.2.1

We are happy to announce the release of Hazelcast Python client 0.2.1, a full-blown Hazelcast Client Protocol implementation targeting Hazelcast 3.6+ clusters and Python 2.7.

· Java Zone

Learn what it’s like to use Hazelcast as the backbone of your Microservices architecture, brought to you in partnership with Hazelcast.

We are happy to announce the release of Hazelcast Python client 0.2.1. This new client is a full-blown Hazelcast Client Protocol implementation targeting Hazelcast 3.6+ clusters and Python 2.7.

In this post, I’ll introduce the general usage of Hazelcast Python client.


You can install the Hazelcast Python client simply by executing either of the following command:

$ python setup.py install

An even simpler way is to install the client from the official Python Package Index:

$ pip install hazelcast-python-client

After installation we’re all set to jump right in.

Getting Started

As a first step, you need a simple configuration. This configuration provides information on how to connect to an already existing Hazelcast cluster and looks as simple as the following example:

import hazelcast

config = hazelcast.ClientConfig()
# Hazelcast.Address is the hostname or IP address, e.g. 'localhost:5701'

After the configuration, you can initialize the client as follows:

client = hazelcast.HazelcastClient(config)

The client object should be created once unless you connect to multiple clusters. And, it should be eventually shut down after using the method client.shutdown().

With our newly created access to the Hazelcast cluster, we now want to read and write data. Same as before, Hazelcast is as simple as possible and access to the distributed map is granted by a single command again:

my_async_map = client.get_map("map-name")

The Python client is designed to be fully asynchronous. Every distributed object function such as map.put, map.get, etc. will return a future to you which works the same way as the Python 3 future class.

You can simply retrieve the operations result from the future:

future = my_map.put("key", "async_val")
old_value = future.result()

Or use it to register callback methods which will be executed asynchronously:

def get_async_callback(f):
    print("map.get_async:", f.result())

future = my_map.get("key")

Although async operations are more efficient in a single threaded Python interpreter, we sometimes need a simpler code. Python client provides a convenience method to support blocking methods.

Every distributed object provides a blocking helper function as shown below.

my_map = client.get_map("map-name").blocking()

Our map implementation is still completely asynchronous internally, but the blocking helper function will call the method result() and return the result instead.

my_map.put("key_1", "value_1")
value = my_map.get("key_1")

Please note that this time the result is returned instead of the future object, compared to the previous example.


Like every Hazelcast client, our Python client also supports adding listeners to distributed objects to retrieve events of different types like entry events, cluster events and more. Adding listeners to our previously created map is also easy:

Python client supports adding listeners to distributed objects.

def item_added(event):
    print("item_added", event)

def item_removed(event):
    print("item_removed", event)

my_map.add_entry_listener(include_value=True, added=item_added, removed=item_removed)

After adding the listeners, the above functions will be called accordingly.


Python client has full support of all Hazelcast internal serialization techniques, including IdentifiedDataSerializable and Portable. Those serialization systems are optimized for different use cases, to learn more about the advantages and disadvantages please see the Hazelcast documentation or our blogpost.

One feature of the Portable serialization is to support server side queries without the need to re-ensemble the same class on the Java side. A simple Portable implementation class is shown below.

from hazelcast.serialization.api import Portable

class Customer(Portable):
    def __init__(self, id=None, name=None, surname=None, mobile=None):
        self.id = id
        self.name = name
        self.surname = surname
        self.mobile = mobile

    def write_portable(self, writer):
        writer.write_int("id", self.id)
        writer.write_utf("name", self.name)
        writer.write_utf("surname", self.surname)
        writer.write_utf("mobile", self.mobile)

    def read_portable(self, reader):
        self.id = reader.read_int("id")
        self.name = reader.read_utf("name")
        self.surname = reader.read_utf("surname")
        self.mobile = reader.read_utf("mobile")

    def get_factory_id(self):
        return FACTORY_ID

    def get_class_id(self):
        return CLASS_ID

Now we need to register the Portable class with our Hazelcast client configuration before we create the client instance.

config = hazelcast.ClientConfig()
config.serialization_config.portable_factories[FACTORY_ID] = \
    {Customer.CLASS_ID: Customer}
client = hazelcast.HazelcastClient(config)
my_map = client.get_map("map").blocking()

After inserting data into the map, you're now able to query information on server side without having an actual Java class.

# my_map is populated with (id, Customer)
sequence = my_map.values(sql("name ILIKE 'Jon%'"))
for customer in sequence:


While the Hazelcast Python client already supports quite a lot of features, the development continues with bug fixes and performance improvements. Please feel free to send your contributions and/or bug reports using the following means:

Learn what it’s like to use Hazelcast as the backbone of your Microservices architecture, brought to you in partnership with Hazelcast.


Published at DZone with permission of Asim Arslan, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

The best of DZone straight to your inbox.

Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}