Skip to content

DOC-547: remove duplicate info from Python readme & add xref #730

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
140 changes: 3 additions & 137 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -24,144 +24,10 @@ 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**
- Similarity search using **VectorCollection** (Beta)
- 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 `many
more <https://hazelcast.com/clients/python/#client-features>`__

Getting Help
------------

You can use the following channels for your questions and
development/usage issues:
For a list of the features available, and for information about how
to install and get started with the client, see the
`Python client documentation <https://docs.hazelcast.com/hazelcast/latest/clients/python>`__.

- `GitHub
repository <https://github.com/hazelcast/hazelcast-python-client/issues/new>`__
- `Documentation <https://hazelcast.readthedocs.io>`__
- `Slack <https://slack.hazelcast.com>`__

Contributing
------------
Expand Down