Python Client

Getting Started

Prerequisites

To run the Python driver, the following is required:

Python 3.9 or newer (3.9, 3.10, 3.11, 3.12 and 3.13 are tested)

Installation

To install Python Client, download it using pip.

pip install pygridgain>=9

After this, you can import pygridgain into your project and use it.

import pygridgain

Limitations

Current release has the following limitations:

Only Distributed Map API is currently available.
The client only works with binary data.

Connecting to Cluster

To connect to the cluster, use the connect() method:

from pygridgain import AsyncClient, EndPoint

address = EndPoint('127.0.0.1', 10800)

async with AsyncClient(address) as client:
    await client.connect()
    # Your code goes here

You can also configure multiple endpoints for the failover and automatic load-balancing:

from pygridgain import AsyncClient, EndPoint

# Alternatively, you can create a collection of addresses.
addresses = [
    EndPoint("127.0.0.1", 10800),
    EndPoint("127.0.0.1", 10801)
]

async with AsyncClient(addresses) as client:
    await client.connect()
    # Your code goes here

Client Configuration

Connection Timeout

You can configure client connection timeout with optional connection_timeout parameter. The client will try to connect for the specified time and fail if no connection is established.

The timeout is specified in seconds. To specify smaller time units, use decimals. For example, 10.5 sets the timeout to 10500 milliseconds.

The example below shows how to set client timeout:

from pygridgain import AsyncClient, EndPoint

address = EndPoint('127.0.0.1', 10800)

async with AsyncClient(address, connection_timeout=20.0) as client:
    await client.connect()
    # Your code goes here

Client Heartbeats

You can configure the client to periodically send messages to the server to keep the connection alive and avoid the idle timeout with an optional heartbeat_interval parameter.

By default, client heartbeat interval is set to 1/3 of ignite.clientConnector.idleTimeoutMillis configuration, or 0.5 seconds, whichever is larger. This configuration is sufficient to keep the client active in most scenarios.

The interval is specified in seconds. To specify smaller time units, use decimals. For example, 10.5 sets the heartbeat interval to 10500 milliseconds.

The example below shows how to set heartbeat interval:

from pygridgain import AsyncClient, EndPoint

address = EndPoint('127.0.0.1', 10800)

async with AsyncClient(address, heartbeat_interval=10.0) as client:
    await client.connect()
    # Your code goes here

SSL Configuration

If the cluster uses SSL encryption, you should specify the ssl configuration to allow the client to connect to the cluster safely. The example below shows how you can provide SSL configuration:

from pygridgain import AsyncClient, EndPoint, SSLConfig

address = EndPoint('127.0.0.1', 10800)
ssl_configuration = SSLConfig(
    protocol_version=ssl.PROTOCOL_TLS,
    cert_reqs=ssl.CERT_OPTIONAL,
    key_file="/path/to/client.key",
    cert_file="/path/to/client.crt",
    ca_file="/path/to/ca.crt"
)

async with AsyncClient(address, ssl_config=ssl_configuration) as client:
    await client.connect()
    # Your code goes here

Authentication

If the cluster has authentication enabled, you should provide user credentials for your connection. The example below shows how you can configure authentication:

from pygridgain import AsyncClient, EndPoint, BasicAuthenticator

address = EndPoint('127.0.0.1', 10800)
auth = BasicAuthenticator("username", "password")

async with AsyncClient(address, authenticator=auth) as client:
    await client.connect()
    # Your code goes here

Working With Distributed Maps

The Python client provides an API for working with distributed maps.

Creating or Getting Map

You can use the get_or_create_binary_map method to get the distributed map. If a map with the specified name exists, the client will get it from the cluster. If not, a new map will be created.

async with AsyncClient(address) as client:
    await client.connect()
    print("client connected")
    binary_map = await client.structures().get_or_create_binary_map('myMap')

Adding Data to Maps

There are 2 methods that can be used to add data to distributed maps:

put method adds a single value.
put_all method adds a batch of values at the same time. Using this method is functionally equivalent to adding values individually with put method, but it works much faster for bigger amount of records..

async with AsyncClient(address) as client:
    await client.connect()
    print("client connected")
    binary_map = await client.structures().get_or_create_binary_map('myMap')

    await binary_map.put(b'1', b'Hello World')
    print(await binary_map.get(b'1'))

    batch_data = {
        b"1": b"Hello World",
        b"2": b"Great World",
        b"3": b"Goodbye World"
    }
    await binary_map.put_all(batch_data)
    print(await binary_map.get(b'3'))

Iterating Maps Entries

Instead of working with entries one by one, you can iterate through all of them:

async with AsyncClient(address) as client:
    await client.connect()
    print("client connected")
    binary_map = await client.structures().get_or_create_binary_map('myMap')

    async for key, value in binary_map:
        print(f'key={key}, value={value}')

Getting Data From Maps

You can check if the specific key exists on the cluster and get it with the following methods:

contains method only checks if the entry exists. It does not retrieve the value.
get method retrieves the value associated with the specified key.

async with AsyncClient(address) as client:
    await client.connect()
    print("client connected")
    binary_map = await client.structures().get_or_create_binary_map('myMap')

    value_exists = await binary_map.contains(b'1')
    print(f"Does 1 exist on the cluster: {value_exists}")

    print(await binary_map.get(b'1'))

Deleting Data in Maps

You can delete data in distributed maps with the following methods:

pop method deletes a specific entry and returns the value it used to contain.
clear method fully removes all data from the distributed map.

async with AsyncClient(address) as client:
    await client.connect()
    print("client connected")
    binary_map = await client.structures().get_or_create_binary_map('myMap')

    popped_value = await binary_map.pop(b"1")
    print(f"POPed user {popped_value}")

    await binary_map.clear()

Checking Map Information

You can get additional information about distributed maps with the following methods:

count method returns the number of entries in the distributed map.
empty checks if the distributed map is empty. This command works much faster than count() == 0 and should be used when you only care about the emptiness of the map.

async with AsyncClient(address) as client:
    await client.connect()
    print("client connected")
    binary_map = await client.structures().get_or_create_binary_map('myMap')

    count = await binary_map.count()
    print(f"Map contains {count} entries")

    is_empty = await binary_map.empty()
    print(f"Map is empty: {is_empty}")

© 2025 GridGain Systems, Inc. All Rights Reserved. Privacy Policy | Legal Notices. GridGain® is a registered trademark of GridGain Systems, Inc.
Apache, Apache Ignite, the Apache feather and the Apache Ignite logo are either registered trademarks or trademarks of The Apache Software Foundation.

Last updated on Sep 17, 2025