Hazelcast Python Client
=======================

.. image:: https://img.shields.io/pypi/v/hazelcast-python-client
    :target: https://pypi.org/project/hazelcast-python-client/
    :alt: PyPI
.. image:: https://img.shields.io/static/v1?label=Github&message=Hazelcast%20Python%20client&style=flat&logo=github
    :target: https://github.com/hazelcast/hazelcast-python-client
    :alt: Github Repository
.. image:: https://img.shields.io/pypi/l/hazelcast-python-client
    :target: https://github.com/hazelcast/hazelcast-python-client/blob/master/LICENSE.txt
    :alt: License

----

`Hazelcast <https://hazelcast.com/>`__ is an open-source distributed
in-memory data store and computation platform that provides a wide
variety of distributed data structures and concurrency primitives.

Hazelcast Python client is a way to communicate to Hazelcast clusters
and access the cluster data. The client provides both a Future-based
asynchronous API, and an asyncio API suitable for wide ranges of use cases.


Overview
--------

Usage
~~~~~

.. code:: python

    from hazelcast import HazelcastClient

    # Connect to Hazelcast cluster.
    client = HazelcastClient()

    # Get or create the "distributed-map" on the cluster.
    distributed_map = client.get_map("distributed-map")

    # Put "key", "value" pair into the "distributed-map" and wait for
    # the request to complete.
    distributed_map.set("key", "value").result()

    # Try to get the value associated with the given key from the cluster
    # and attach a callback to be executed once the response for the
    # get request is received. Note that, the set request above was
    # blocking since it calls ".result()" on the returned Future, whereas
    # the get request below is non-blocking.
    get_future = distributed_map.get("key")
    get_future.add_done_callback(lambda future: print(future.result()))

    # Do other operations. The operations below won't wait for
    # the get request above to complete.

    print("Map size:", distributed_map.size().result())

    # Shutdown the client.
    client.shutdown()

Usage (Asyncio)
~~~~~~~~~~~~~~~

.. code:: python

    import asyncio

    from hazelcast.asyncio import HazelcastClient

    async def amain():
        # Connect to Hazelcast cluster.
        client = await HazelcastClient.create_and_start()

        # Get or create the "distributed-map" on the cluster.
        distributed_map = await client.get_map("distributed-map")

        # Put "key", "value" pair into the "distributed-map".
        # And wait for the request to complete.
        await distributed_map.set("key", "value")

        # Try to get the value associated with the given key from the cluster
        # and attach a callback to be executed once the response for the
        # get request is received. Note that, the set request above was
        # synchronous, since the result is awaited.
        # Whereas the get request below is asynchronous.
        get_future = asyncio.create_task(distributed_map.get("key"))
        get_future.add_done_callback(lambda future: print("Future's value:", future.result()))

        # Do other operations. The operations below won't wait for
        # the get request above to complete.
        map_size = await distributed_map.size()
        print("Map size:", map_size)

        # Shutdown the client.
        await client.shutdown()


    asyncio.run(amain())

If you are using Hazelcast and the Python client on the same machine,
the default configuration should work out-of-the-box. However,
you may need to configure the client to connect to cluster nodes that
are running on different machines or to customize client properties.

Configuration
~~~~~~~~~~~~~

.. code:: python

    client = HazelcastClient(
        cluster_name="cluster-name",
        cluster_members=[
            "10.90.0.2:5701",
            "10.90.0.3:5701",
        ],
        lifecycle_listeners=[
            lambda state: print("Lifecycle event >>>", state),
        ]
    )

Configuration (Asyncio)
~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

    client = await HazelcastClient.create_and_start(
        cluster_name="cluster-name",
        cluster_members=[
            "10.90.0.2:5701",
            "10.90.0.3:5701",
        ],
        lifecycle_listeners=[
            lambda state: print("Lifecycle event >>>", state),
        ]
    )


See the API documentation of :class:`hazelcast.client.HazelcastClient`
to learn more about supported configuration options.

Features
--------

-  Distributed, partitioned and queryable in-memory key-value store
   implementation, called **Map**
-  Eventually consistent cache implementation to store a subset of the
   Map data locally in the memory of the client, called **Near Cache**
-  Additional data structures and simple messaging constructs such as
   **Set**, **MultiMap**, **Queue**, **Topic**
-  Cluster-wide unique ID generator, called **FlakeIdGenerator**
-  Distributed, CRDT based counter, called **PNCounter**
-  Distributed concurrency primitives from CP Subsystem such as
   **FencedLock**, **Semaphore**, **AtomicLong**
-  Integration with `Hazelcast Cloud <https://cloud.hazelcast.com/>`__
-  Support for serverless and traditional web service architectures with
   **Unisocket** and **Smart** operation modes
-  Ability to listen to client lifecycle, cluster state, and distributed
   data structure events
-  and :ref:`many more<features:features>`


.. toctree::
    :hidden:

    client
    asyncio_client
    config
    api/modules
    getting_started
    getting_started_asyncio
    features
    configuration_overview
    serialization
    setting_up_client_network
    client_connection_strategy
    using_python_client_with_hazelcast
    sql
    securing_client_connection
    development_and_testing
    getting_help
    contributing
    license
    copyright