Hazelcast Python Client

5.6.0 verified Mon Apr 27 auth: no python

Python client for Hazelcast, an open-source in-memory data grid. Current version 5.6.0 (requires Python 3.11+). Released approximately quarterly.

pip install hazelcast-python-client

Common errors

error ImportError: cannot import name 'HazelcastClient' from 'hazelcast' ↓

cause Common mistake: `import hazelcast` does not expose HazelcastClient.

fix

Use from hazelcast.client import HazelcastClient

error AttributeError: 'Future' object has no attribute 'join' ↓

cause Using threading.Thread's join incorrectly; Hazelcast futures use .result() not .join().

fix

Call .result() on the future to wait for the operation to complete.

error hazelcast.errors.HazelcastClientNotActiveError: HazelcastClientNotActiveError() ↓

cause Attempting operations after client.shutdown() or before client is fully connected.

fix

Ensure client lifecycle management: create client, perform operations, then shutdown.

Warnings

breaking Async operations now require calling .result() on futures; direct await is only available in asyncio module (Beta). ↓

fix Use client.get_map('m').get('key').result() for synchronous, or switch to hazelcast.asyncio module.

breaking Python 3.11 minimum required starting from v5.6.0. ↓

fix Upgrade Python to 3.11 or higher.

gotcha Default serialization uses Python pickle for unrecognized types, which can be a security risk when connecting to untrusted clusters. ↓

fix Configure a custom serialization serializer or allow only trusted clusters.

Imports

HazelcastClient

wrong

import hazelcast

correct

from hazelcast.client import HazelcastClient

hazelcast alone doesn't import client

ClientConfig

wrong

from hazelcast.config import ClientConfig

correct

from hazelcast.client import ClientConfig

ClientConfig is in hazelcast.client

Quickstart

Connect to a Hazelcast cluster, use a distributed map.

from hazelcast.client import HazelcastClient, ClientConfig
config = ClientConfig()
config.cluster_name = os.environ.get('HZ_CLUSTER_NAME', 'hello-world')
config.cluster_members = [os.environ.get('HZ_MEMBER_ADDRESS', '127.0.0.1:5701')]
client = HazelcastClient(config)
my_map = client.get_map('my-distributed-map')
my_map.set('key', 'value').result()
print(my_map.get('key').result())
client.shutdown()