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/readthedocs/hazelcast
:target: https://hazelcast.readthedocs.io
:alt: Read the Docs
.. image:: https://img.shields.io/badge/slack-chat-green.svg
:target: https://slack.hazelcast.com
:alt: Join the community on Slack
.. 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 a Future-based
asynchronous API suitable for wide ranges of use cases.
Installation
------------
Hazelcast
~~~~~~~~~
Hazelcast Python client requires a working Hazelcast cluster to run.
This cluster handles the storage and manipulation of the user data.
A Hazelcast cluster consists of one or more cluster members. These
members generally run on multiple virtual or physical machines and are
connected to each other via the network. Any data put on the cluster is
partitioned to multiple members transparent to the user. It is therefore
very easy to scale the system by adding new members as the data grows.
Hazelcast cluster also offers resilience. Should any hardware or
software problem causes a crash to any member, the data on that member
is recovered from backups and the cluster continues to operate without
any downtime.
The quickest way to start a single member cluster for development
purposes is to use our `Docker
images <https://hub.docker.com/r/hazelcast/hazelcast/>`__.
.. code:: bash
docker run -p 5701:5701 hazelcast/hazelcast:5.3.0
You can also use our ZIP or TAR
`distributions <https://hazelcast.com/open-source-projects/downloads/>`__.
Once you have downloaded, you can start the Hazelcast member using
the ``bin/hz-start`` script.
Client
~~~~~~
.. code:: bash
pip install hazelcast-python-client
Overview
--------
Usage
~~~~~
.. code:: python
import hazelcast
# Connect to Hazelcast cluster.
client = hazelcast.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()
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
import hazelcast
client = hazelcast.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),
]
)
print("Connected to cluster")
client.shutdown()
Refer to `the documentation <https://hazelcast.readthedocs.io>`__
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 Viridian <https://viridian.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 `many
more <https://hazelcast.com/clients/python/#client-features>`__
Getting Help
------------
You can use the following channels for your questions and
development/usage issues:
- `GitHub
repository <https://github.com/hazelcast/hazelcast-python-client/issues/new>`__
- `Documentation <https://hazelcast.readthedocs.io>`__
- `Slack <https://slack.hazelcast.com>`__
- `Google Groups <https://groups.google.com/g/hazelcast>`__
- `Stack
Overflow <https://stackoverflow.com/questions/tagged/hazelcast>`__
Contributing
------------
We encourage any type of contribution in the form of issue reports or
pull requests.
Issue Reports
~~~~~~~~~~~~~
For issue reports, please share the following information with us to
quickly resolve the problems:
- Hazelcast and the client version that you use
- General information about the environment and the architecture you
use like Python version, cluster size, number of clients, Java
version, JVM parameters, operating system etc.
- Logs and stack traces, if any
- Detailed description of the steps to reproduce the issue
Pull Requests
~~~~~~~~~~~~~
Contributions are submitted, reviewed and accepted using the pull
requests on GitHub. For an enhancement or larger feature, please
create a GitHub issue first to discuss.
Development
^^^^^^^^^^^
1. Clone the `GitHub repository
<https://github.com/hazelcast/hazelcast-python-client>`__.
2. Run ``python setup.py install`` to install the Python client.
If you are planning to contribute:
1. Run ``pip install -r requirements-dev.txt`` to install development
dependencies.
2. Use `black <https://pypi.org/project/black/>`__ to reformat the code
by running the ``black --config black.toml .`` command.
3. Use `mypy <https://pypi.org/project/mypy/>`__ to check type annotations
by running the ``mypy hazelcast`` command.
4. Make sure that tests are passing by following the steps described
in the next section.
Testing
^^^^^^^
In order to test Hazelcast Python client locally, you will need the
following:
- Java 8 or newer
- Maven
Following commands starts the tests:
.. code:: bash
python run_tests.py
Test script automatically downloads ``hazelcast-remote-controller`` and
Hazelcast. The script uses Maven to download those.
License
-------
`Apache 2.0 License <LICENSE>`__.
Copyright
---------
Copyright (c) 2008-2023, Hazelcast, Inc. All Rights Reserved.
Visit `hazelcast.com <https://hazelcast.com>`__ for more
information.
Raw data
{
"_id": null,
"home_page": "https://github.com/hazelcast/hazelcast-python-client",
"name": "hazelcast-python-client",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "hazelcast,hazelcast client,In-Memory Data Grid,Distributed Computing",
"author": "Hazelcast Inc. Developers",
"author_email": "hazelcast@googlegroups.com",
"download_url": "https://files.pythonhosted.org/packages/76/50/1ca295b2a9c8ba695cf7c4bf83c36dfa2d9313a2d6260823fc605f705326/hazelcast-python-client-5.3.0.tar.gz",
"platform": null,
"description": "Hazelcast Python Client\n=======================\n\n.. image:: https://img.shields.io/pypi/v/hazelcast-python-client\n :target: https://pypi.org/project/hazelcast-python-client/\n :alt: PyPI\n.. image:: https://img.shields.io/readthedocs/hazelcast\n :target: https://hazelcast.readthedocs.io\n :alt: Read the Docs\n.. image:: https://img.shields.io/badge/slack-chat-green.svg\n :target: https://slack.hazelcast.com\n :alt: Join the community on Slack\n.. image:: https://img.shields.io/pypi/l/hazelcast-python-client\n :target: https://github.com/hazelcast/hazelcast-python-client/blob/master/LICENSE.txt\n :alt: License\n\n----\n\n`Hazelcast <https://hazelcast.com/>`__ is an open-source distributed\nin-memory data store and computation platform that provides a wide\nvariety of distributed data structures and concurrency primitives.\n\nHazelcast Python client is a way to communicate to Hazelcast clusters\nand access the cluster data. The client provides a Future-based\nasynchronous API suitable for wide ranges of use cases.\n\nInstallation\n------------\n\nHazelcast\n~~~~~~~~~\n\nHazelcast Python client requires a working Hazelcast cluster to run.\nThis cluster handles the storage and manipulation of the user data.\n\nA Hazelcast cluster consists of one or more cluster members. These\nmembers generally run on multiple virtual or physical machines and are\nconnected to each other via the network. Any data put on the cluster is\npartitioned to multiple members transparent to the user. It is therefore\nvery easy to scale the system by adding new members as the data grows.\nHazelcast cluster also offers resilience. Should any hardware or\nsoftware problem causes a crash to any member, the data on that member\nis recovered from backups and the cluster continues to operate without\nany downtime.\n\nThe quickest way to start a single member cluster for development\npurposes is to use our `Docker\nimages <https://hub.docker.com/r/hazelcast/hazelcast/>`__.\n\n.. code:: bash\n\n docker run -p 5701:5701 hazelcast/hazelcast:5.3.0\n\nYou can also use our ZIP or TAR\n`distributions <https://hazelcast.com/open-source-projects/downloads/>`__.\nOnce you have downloaded, you can start the Hazelcast member using\nthe ``bin/hz-start`` script.\n\nClient\n~~~~~~\n\n.. code:: bash\n\n pip install hazelcast-python-client\n\nOverview\n--------\n\nUsage\n~~~~~\n\n.. code:: python\n\n import hazelcast\n\n # Connect to Hazelcast cluster.\n client = hazelcast.HazelcastClient()\n\n # Get or create the \"distributed-map\" on the cluster.\n distributed_map = client.get_map(\"distributed-map\")\n\n # Put \"key\", \"value\" pair into the \"distributed-map\" and wait for\n # the request to complete.\n distributed_map.set(\"key\", \"value\").result()\n\n # Try to get the value associated with the given key from the cluster\n # and attach a callback to be executed once the response for the\n # get request is received. Note that, the set request above was\n # blocking since it calls \".result()\" on the returned Future, whereas\n # the get request below is non-blocking.\n get_future = distributed_map.get(\"key\")\n get_future.add_done_callback(lambda future: print(future.result()))\n\n # Do other operations. The operations below won't wait for\n # the get request above to complete.\n\n print(\"Map size:\", distributed_map.size().result())\n\n # Shutdown the client.\n client.shutdown()\n\n\nIf you are using Hazelcast and the Python client on the same machine,\nthe default configuration should work out-of-the-box. However,\nyou may need to configure the client to connect to cluster nodes that\nare running on different machines or to customize client properties.\n\nConfiguration\n~~~~~~~~~~~~~\n\n.. code:: python\n\n import hazelcast\n\n client = hazelcast.HazelcastClient(\n cluster_name=\"cluster-name\",\n cluster_members=[\n \"10.90.0.2:5701\",\n \"10.90.0.3:5701\",\n ],\n lifecycle_listeners=[\n lambda state: print(\"Lifecycle event >>>\", state),\n ]\n )\n\n print(\"Connected to cluster\")\n client.shutdown()\n\n\nRefer to `the documentation <https://hazelcast.readthedocs.io>`__\nto learn more about supported configuration options.\n\nFeatures\n--------\n\n- Distributed, partitioned and queryable in-memory key-value store\n implementation, called **Map**\n- Eventually consistent cache implementation to store a subset of the\n Map data locally in the memory of the client, called **Near Cache**\n- Additional data structures and simple messaging constructs such as\n **Set**, **MultiMap**, **Queue**, **Topic**\n- Cluster-wide unique ID generator, called **FlakeIdGenerator**\n- Distributed, CRDT based counter, called **PNCounter**\n- Distributed concurrency primitives from CP Subsystem such as\n **FencedLock**, **Semaphore**, **AtomicLong**\n- Integration with `Hazelcast Viridian <https://viridian.hazelcast.com/>`__\n- Support for serverless and traditional web service architectures with\n **Unisocket** and **Smart** operation modes\n- Ability to listen to client lifecycle, cluster state, and distributed\n data structure events\n- and `many\n more <https://hazelcast.com/clients/python/#client-features>`__\n\nGetting Help\n------------\n\nYou can use the following channels for your questions and\ndevelopment/usage issues:\n\n- `GitHub\n repository <https://github.com/hazelcast/hazelcast-python-client/issues/new>`__\n- `Documentation <https://hazelcast.readthedocs.io>`__\n- `Slack <https://slack.hazelcast.com>`__\n- `Google Groups <https://groups.google.com/g/hazelcast>`__\n- `Stack\n Overflow <https://stackoverflow.com/questions/tagged/hazelcast>`__\n\nContributing\n------------\n\nWe encourage any type of contribution in the form of issue reports or\npull requests.\n\nIssue Reports\n~~~~~~~~~~~~~\n\nFor issue reports, please share the following information with us to\nquickly resolve the problems:\n\n- Hazelcast and the client version that you use\n- General information about the environment and the architecture you\n use like Python version, cluster size, number of clients, Java\n version, JVM parameters, operating system etc.\n- Logs and stack traces, if any\n- Detailed description of the steps to reproduce the issue\n\nPull Requests\n~~~~~~~~~~~~~\n\nContributions are submitted, reviewed and accepted using the pull\nrequests on GitHub. For an enhancement or larger feature, please\ncreate a GitHub issue first to discuss.\n\nDevelopment\n^^^^^^^^^^^\n\n1. Clone the `GitHub repository\n <https://github.com/hazelcast/hazelcast-python-client>`__.\n2. Run ``python setup.py install`` to install the Python client.\n\nIf you are planning to contribute:\n\n1. Run ``pip install -r requirements-dev.txt`` to install development\n dependencies.\n2. Use `black <https://pypi.org/project/black/>`__ to reformat the code\n by running the ``black --config black.toml .`` command.\n3. Use `mypy <https://pypi.org/project/mypy/>`__ to check type annotations\n by running the ``mypy hazelcast`` command.\n4. Make sure that tests are passing by following the steps described\n in the next section.\n\nTesting\n^^^^^^^\n\nIn order to test Hazelcast Python client locally, you will need the\nfollowing:\n\n- Java 8 or newer\n- Maven\n\nFollowing commands starts the tests:\n\n.. code:: bash\n\n python run_tests.py\n\nTest script automatically downloads ``hazelcast-remote-controller`` and\nHazelcast. The script uses Maven to download those.\n\nLicense\n-------\n\n`Apache 2.0 License <LICENSE>`__.\n\nCopyright\n---------\n\nCopyright (c) 2008-2023, Hazelcast, Inc.\u00a0All Rights Reserved.\n\nVisit `hazelcast.com <https://hazelcast.com>`__ for more\ninformation.\n\n\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Hazelcast Python Client",
"version": "5.3.0",
"project_urls": {
"Homepage": "https://github.com/hazelcast/hazelcast-python-client"
},
"split_keywords": [
"hazelcast",
"hazelcast client",
"in-memory data grid",
"distributed computing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2b5630d5224930dba8c37ac00b38f8ae15197795c7d60e1a2ca476aec601510f",
"md5": "3f1733868a7277a6659fa6a0229f8c33",
"sha256": "effba1748ba57b2dbb1a5aaa912e52ee039ed49f2d20dab7540fe7ac9c72688c"
},
"downloads": -1,
"filename": "hazelcast_python_client-5.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3f1733868a7277a6659fa6a0229f8c33",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 432866,
"upload_time": "2023-06-12T14:32:53",
"upload_time_iso_8601": "2023-06-12T14:32:53.718575Z",
"url": "https://files.pythonhosted.org/packages/2b/56/30d5224930dba8c37ac00b38f8ae15197795c7d60e1a2ca476aec601510f/hazelcast_python_client-5.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "76501ca295b2a9c8ba695cf7c4bf83c36dfa2d9313a2d6260823fc605f705326",
"md5": "288277e8b92e65517a58122980b77518",
"sha256": "9defd4adf4d25d66ca49383c78d8762960ae6ab96a3e1fecaa729b026542a5fc"
},
"downloads": -1,
"filename": "hazelcast-python-client-5.3.0.tar.gz",
"has_sig": false,
"md5_digest": "288277e8b92e65517a58122980b77518",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 242038,
"upload_time": "2023-06-12T14:32:55",
"upload_time_iso_8601": "2023-06-12T14:32:55.795007Z",
"url": "https://files.pythonhosted.org/packages/76/50/1ca295b2a9c8ba695cf7c4bf83c36dfa2d9313a2d6260823fc605f705326/hazelcast-python-client-5.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-12 14:32:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hazelcast",
"github_project": "hazelcast-python-client",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "hazelcast-python-client"
}
JSON
