Skip to content

Commit 8c3064d

Browse files
devOpsHazelcastamandalindsay
devOpsHazelcast
and
amandalindsay
authored
DOC-546: include install & get started info from readme [v/5.6] (#1963)
Backport of #1783 For https://hazelcast.atlassian.net/browse/DOC-546 - include get started & installation instructions, basic config and usage. This is existing info in the Python client readme and the 'readthedocs' site which has been scrubbed. Co-authored-by: Amanda Lindsay <[email protected]>
1 parent f2415a2 commit 8c3064d

File tree

1 file changed

+138
-10
lines changed

1 file changed

+138
-10
lines changed

‎docs/modules/clients/pages/python.adoc‎

Lines changed: 138 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,149 @@
11
= Python Client
22
:page-api-reference: https://hazelcast.readthedocs.io/en/v{page-latest-supported-python-client}/index.html
33

4-
TIP: For the latest Python API documentation, see https://hazelcast.readthedocs.io/en/v{page-latest-supported-python-client}/index.html[Hazelcast Python Client docs].
4+
== Overview
5+
6+
This section provides information about the Python client for Hazelcast, and explains how to install and use the client.
7+
8+
TIP: To learn how to get started quickly with the Hazelcast Python client, follow our simple xref:clients:python-client-getting-started.adoc[Get started with Python] tutorial.
59

610
The Hazelcast native Python client is an official library that allows Python applications to connect to and interact with Hazelcast clusters. It is implemented using the Hazelcast Open Binary Client Protocol. The key features and benefits include:
711

8-
* Distributed Data Structures: the client provides access to Hazelcast's distributed data structures such as maps, queues, topics, lists, sets, and more
9-
* SQL Support: it offers the ability to query Map data using standard SQL syntax
10-
* JSON Object Support: it allows using and querying JSON objects
11-
* Compact Serialization: the client supports Compact serialization, which provides efficient serialization for objects
12-
* DBAPI Support: it implements the DBAPI interface on top of the SQL service, making it compatible with various libraries and tools
13-
* Near Cache: the client supports the Near Cache feature for faster read speeds on frequently accessed data
14-
* Integration with Jupyter Notebook: the client can be used in Jupyter Notebook environments, enabling interactive data analysis and visualization
12+
* Distributed data structures: the client provides access to Hazelcast's distributed data structures such as maps, queues, topics, lists, sets, and more.
13+
* SQL support: it offers the ability to query Map data using standard SQL syntax.
14+
* JSON object support: it allows using and querying JSON objects.
15+
* Compact serialization: the client supports compact serialization, which provides efficient serialization of objects.
16+
* DBAPI support: it implements the DBAPI interface on top of the SQL service, making it compatible with various libraries and tools.
17+
* Near cache: the client supports the near cache feature for faster reads on frequently accessed data.
1518

1619
These features make the Hazelcast Python Client a powerful tool for Python applications requiring distributed computing, in-memory data processing, and real-time analytics capabilities.
1720

21+
TIP: For the latest Python API documentation, see https://hazelcast.readthedocs.io/en/v{page-latest-supported-python-client}/index.html[Hazelcast Python Client docs].
22+
23+
== Install the Python client
24+
25+
This section explains how to set up a Hazelcast cluster and install the Hazelcast Python client.
26+
27+
=== Set up a Hazelcast cluster
28+
29+
The Hazelcast Python client requires a working Hazelcast cluster to run. The cluster handles storage and manipulation of the user data. Clients are a way to connect to the Hazelcast cluster and access the data.
30+
31+
The quickest way to start a single member cluster for development purposes is to use our https://hub.docker.com/r/hazelcast/hazelcast/[Docker images].
32+
33+
Launch a Hazelcast Docker Container by running the following command:
34+
35+
```bash
36+
docker run -p 5701:5701 hazelcast/hazelcast:5.3.0
37+
```
38+
TIP: For a step-by-step guide, see the https://docs.hazelcast.com/hazelcast/latest/getting-started/get-started-docker[Start a local cluster in Docker] and https://docs.hazelcast.com/hazelcast/latest/getting-started/enterprise-overview[Get Started with Hazelcast Enterprise Edition] tutorials.
39+
40+
Alternatively, you can run standalone members by downloading and running distribution files from the Hazelcast website as follows:
41+
42+
. Go to the download page and choose either the https://hazelcast.com/open-source-projects/downloads/[ZIP or TAR distribution] of Hazelcast.
43+
. Decompress the contents into the directory that you want to run members from.
44+
. Change into this directory and then start the Hazelcast member using the ``bin/hz-start`` script.
45+
46+
The Hazelcast log appears in the terminal showing that your 1-member cluster is ready to be used.
47+
48+
For more information on setting up a Hazelcast cluster, see the https://hazelcast.readthedocs.io/en/latest/getting_started.html[Python client documentation].
49+
50+
=== Download and install the client
51+
52+
You can download and install the Python client from PyPI (the Python Package Index) using pip. This library allows your Python applications to connect to and interact with a Hazelcast cluster, enabling you to use distributed data structures and other Hazelcast features in your Python code.
53+
54+
To download and install the client, run:
55+
56+
```bash
57+
pip install hazelcast-python-client
58+
```
59+
60+
== Use the client
61+
62+
This section shows how to connect to a Hazelcast cluster and perform some basic operations using the client.
63+
64+
*Example: Connect to a Hazelcast cluster*
65+
66+
```python
67+
import hazelcast
68+
69+
client = hazelcast.HazelcastClient()
70+
```
71+
72+
*Example: Get or create the "distributed-map" on the cluster*
73+
74+
```python
75+
distributed_map = client.get_map("distributed-map")
76+
```
77+
78+
*Example: Put "key", "value" pair into the "distributed-map"*
79+
80+
In this example, you will have to wait for the request to complete.
81+
82+
```python
83+
distributed_map.set("key", "value").result()
84+
```
85+
86+
*Example: Get the value associated with the given key from the cluster*
87+
88+
In this example, you will attach a callback to be executed once the response for the get request is received.
89+
Note that, the set request above is blocking since it calls ".result()" on the returned Future,
90+
whereas the get request below is non-blocking.
91+
92+
```python
93+
get_future = distributed_map.get("key")
94+
get_future.add_done_callback(lambda future: print(future.result()))
95+
```
96+
97+
Note that further operations will not wait for the get request above to complete.
98+
99+
*Example: Print the map and shut down the client*
100+
101+
```python
102+
print("Map size:", distributed_map.size().result())
103+
client.shutdown()
104+
```
105+
106+
For more code samples, see the https://github.com/hazelcast/hazelcast-python-client/tree/master/examples[Hazelcast Python examples].
107+
108+
== Configure the client
109+
110+
If you are running Hazelcast and the Python client on the same machine, the default configuration should work out-of-the-box.
111+
However, if you run the client on a different computer to that of the cluster members, you may need to do some simple configuration, such as specifying member addresses, or customizing client properties.
112+
113+
The following shows some basic configuration settings:
114+
115+
```python
116+
import hazelcast
117+
118+
client = hazelcast.HazelcastClient(
119+
cluster_name="cluster-name",
120+
cluster_members=[
121+
"10.90.0.2:5701",
122+
"10.90.0.3:5701",
123+
],
124+
lifecycle_listeners=[
125+
lambda state: print("Lifecycle event >>>", state),
126+
]
127+
)
128+
129+
print("Connected to cluster")
130+
client.shutdown()
131+
```
132+
133+
For detailed network configurations and additional features of Hazelcast Python client configuration, see the
134+
https://hazelcast.readthedocs.io/en/latest/configuration_overview.html#configuration-overview[Configuration overview]
135+
and https://hazelcast.readthedocs.io/en/latest/getting_started.html#configuring-hazelcast-python-client[Configuring Hazelcast Python client].
136+
137+
== Get support
138+
139+
Join us in the https://hazelcastcommunity.slack.com/channels/python-client[Python client channel].
140+
Get an invite via https://slack.hazelcast.com/[Slack].
141+
142+
Raise an issue in the https://github.com/hazelcast/hazelcast-python-client/issues[GitHub repository].
143+
18144
== Next steps
19145

20-
For more information, see the Hazelcast Python client GitHub https://github.com/hazelcast/hazelcast-python-client[repo^]
21-
and https://github.com/hazelcast/hazelcast-python-client/tree/master/examples[code samples^].
146+
For more information:
147+
148+
- See the Hazelcast Python Client GitHub https://github.com/hazelcast/hazelcast-python-client[repo^]
149+
- Find https://github.com/hazelcast/hazelcast-python-client/tree/master/examples[code samples^]

0 commit comments

Comments
 (0)