Skip to content

Commit bcb07a1

Browse files
isapegoivandasch
isapego
and
ivandasch
authored
GG-33031 [IGNITE-14418] Update documentation and examples (#40)
(cherry picked from commit 70bb1d9) Co-authored-by: Ivan Dashchinskiy <ivandasch@gmail.com>
1 parent 832cf97 commit bcb07a1

50 files changed

Lines changed: 1722 additions & 540 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,29 @@ This code implies that it is run in the environment with `pygridgain` package
100100
installed, and GridGain node is running on localhost:10800.
101101

102102
## Testing
103-
Run
103+
*NB!* It is recommended installing `pygridgain` in development mode.
104+
Refer to [this section](#for-developer) for instructions.
105+
106+
Do not forget to install test requirements:
107+
```bash
108+
$ pip install -r requirements/install.txt -r requirements/tests.txt
109+
```
110+
111+
Also, you'll need to have a binary release of Ignite with `log4j2` enabled and to set
112+
`IGNITE_HOME` environment variable:
113+
```bash
114+
$ cd <ignite_binary_release>
115+
$ export IGNITE_HOME=$(pwd)
116+
$ cp -r $IGNITE_HOME/libs/optional/ignite-log4j2 $IGNITE_HOME/libs/
104117
```
105-
$ python setup.py pytest
106-
```
118+
### Run basic tests
119+
```bash
120+
$ pytest
121+
```
122+
### Run with examples
123+
```bash
124+
$ pytest --examples
125+
```
126+
127+
If you need to change the connection parameters, see the documentation on
128+
[testing](https://pygridgain.readthedocs.io/en/latest/readme.html#testing).

‎docs/async_examples.rst‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
.. Copyright 2021 GridGain Systems, Inc. and Contributors.
2+
3+
.. Licensed under the GridGain Community Edition License (the "License");
4+
you may not use this file except in compliance with the License.
5+
You may obtain a copy of the License at
6+
7+
.. https://www.gridgain.com/products/software/community-edition/gridgain-community-edition-license
8+
9+
.. Unless required by applicable law or agreed to in writing, software
10+
distributed under the License is distributed on an "AS IS" BASIS,
11+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
See the License for the specific language governing permissions and
13+
limitations under the License.
14+
15+
.. _async_examples_of_usage:
16+
17+
============================
18+
Asynchronous client examples
19+
============================
20+
File: `async_key_value.py`_.
21+
22+
Basic usage
23+
-----------
24+
Asynchronous client and cache (:py:class:`~pygridgain.aio_client.AioClient` and :py:class:`~pygridgain.aio_cache.AioCache`)
25+
has mostly the same API as synchronous ones (:py:class:`~pygridgain.client.Client` and :py:class:`~pygridgain.cache.Cache`).
26+
But there is some peculiarities.
27+
28+
Basic key-value
29+
===============
30+
Firstly, import dependencies.
31+
32+
.. literalinclude:: ../examples/async_key_value.py
33+
:language: python
34+
:lines: 18
35+
36+
Let's connect to cluster and perform key-value queries.
37+
38+
.. literalinclude:: ../examples/async_key_value.py
39+
:language: python
40+
:dedent: 4
41+
:lines: 23-38
42+
43+
Scan
44+
====
45+
The :py:meth:`~pygridgain.aio_cache.AioСache.scan` method returns :py:class:`~pygridgain.cursors.AioScanCursor`,
46+
that yields the resulting rows.
47+
48+
.. literalinclude:: ../examples/async_key_value.py
49+
:language: python
50+
:dedent: 4
51+
:lines: 39-50
52+
53+
54+
File: `async_sql.py`_.
55+
56+
SQL
57+
---
58+
59+
First let us establish a connection.
60+
61+
.. literalinclude:: ../examples/async_sql.py
62+
:language: python
63+
:dedent: 4
64+
:lines: 197-198
65+
66+
Then create tables. Begin with `Country` table, than proceed with related
67+
tables `City` and `CountryLanguage`.
68+
69+
.. literalinclude:: ../examples/async_sql.py
70+
:language: python
71+
:lines: 25-42, 51-59, 67-74
72+
73+
.. literalinclude:: ../examples/async_sql.py
74+
:language: python
75+
:dedent: 4
76+
:lines: 199-205
77+
78+
Create indexes.
79+
80+
.. literalinclude:: ../examples/async_sql.py
81+
:language: python
82+
:lines: 60-62, 75-77
83+
84+
.. literalinclude:: ../examples/async_sql.py
85+
:language: python
86+
:dedent: 8
87+
:lines: 207-209
88+
89+
Fill tables with data.
90+
91+
.. literalinclude:: ../examples/async_sql.py
92+
:language: python
93+
:lines: 43-50, 63-66, 78-81
94+
95+
.. literalinclude:: ../examples/async_sql.py
96+
:language: python
97+
:dedent: 8
98+
:lines: 212-223
99+
100+
Now let us answer some questions.
101+
102+
What are the 10 largest cities in our data sample (population-wise)?
103+
====================================================================
104+
105+
.. literalinclude:: ../examples/async_sql.py
106+
:language: python
107+
:dedent: 8
108+
:lines: 225-243
109+
110+
The :py:meth:`~pygridgain.aio_client.AioClient.sql` method returns :py:class:`~pygridgain.cursors.AioSqlFieldsCursor`,
111+
that yields the resulting rows.
112+
113+
What are the 10 most populated cities throughout the 3 chosen countries?
114+
========================================================================
115+
116+
If you set the `include_field_names` argument to `True`, the
117+
:py:meth:`~pygridgain.client.Client.sql` method will generate a list of
118+
column names as a first yield. Unfortunately, there is no async equivalent of `next` but
119+
you can await :py:meth:`__anext__()`
120+
of :py:class:`~pygridgain.cursors.AioSqlFieldsCursor`
121+
122+
.. literalinclude:: ../examples/async_sql.py
123+
:language: python
124+
:dedent: 8
125+
:lines: 246-271
126+
127+
Display all the information about a given city
128+
==============================================
129+
130+
.. literalinclude:: ../examples/async_sql.py
131+
:language: python
132+
:dedent: 8
133+
:lines: 273-288
134+
135+
Finally, delete the tables used in this example with the following queries:
136+
137+
.. literalinclude:: ../examples/async_sql.py
138+
:language: python
139+
:lines: 83
140+
141+
.. literalinclude:: ../examples/async_sql.py
142+
:language: python
143+
:dedent: 8
144+
:lines: 290-297
145+
146+
147+
148+
149+
.. _async_key_value.py: https://github.com/apache/ignite-python-thin-client/blob/master/examples/async_key_value.py
150+
.. _async_sql.py: https://github.com/apache/ignite-python-thin-client/blob/master/examples/async_sql.py

‎docs/conf.py‎

Lines changed: 19 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,20 @@
1-
# -*- coding: utf-8 -*-
1+
#
2+
# Copyright 2021 GridGain Systems, Inc. and Contributors.
3+
#
4+
# Licensed under the GridGain Community Edition License (the "License");
5+
# you may not use this file except in compliance with the License.
6+
# You may obtain a copy of the License at
7+
#
8+
# https://www.gridgain.com/products/software/community-edition/gridgain-community-edition-license
9+
#
10+
# Unless required by applicable law or agreed to in writing, software
11+
# distributed under the License is distributed on an "AS IS" BASIS,
12+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
# See the License for the specific language governing permissions and
14+
# limitations under the License.
15+
#
16+
17+
218
#
319
# Configuration file for the Sphinx documentation builder.
420
#
@@ -14,6 +30,8 @@
1430
#
1531
import os
1632
import sys
33+
34+
1735
sys.path.insert(0, os.path.abspath('../'))
1836

1937

@@ -23,11 +41,6 @@
2341
copyright = '2018-2021, GridGain Community Edition License'
2442
author = 'GridGain Systems, Inc.'
2543

26-
# The short X.Y version
27-
version = ''
28-
# The full version, including alpha/beta/rc tags
29-
release = '0.1.0'
30-
3144

3245
# -- General configuration ---------------------------------------------------
3346

‎docs/datatypes/cache_props.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,9 @@ matters.
3030
| name | value | type | |
3131
+=======================================+==========+==========+=======================================================+
3232
| Read/write cache properties, used to configure cache via :py:meth:`~pygridgain.client.Client.create_cache` or |
33-
| :py:meth:`~pygridgain.client.Client.get_or_create_cache` |
33+
| :py:meth:`~pygridgain.client.Client.get_or_create_cache` of :py:class:`~pygridgain.client.Client` |
34+
| (:py:meth:`~pygridgain.aio_client.AioClient.create_cache` or |
35+
| :py:meth:`~pygridgain.aio_client.AioClient.get_or_create_cache` of :py:class:`~pygridgain.aio_client.AioClient`). |
3436
+---------------------------------------+----------+----------+-------------------------------------------------------+
3537
| PROP_NAME | 0 | str | Cache name. This is the only *required* property. |
3638
+---------------------------------------+----------+----------+-------------------------------------------------------+
@@ -97,8 +99,6 @@ matters.
9799
+---------------------------------------+----------+----------+-------------------------------------------------------+
98100
| Read-only cache properties. Can not be set, but only retrieved via :py:meth:`~pygridgain.cache.Cache.settings` |
99101
+---------------------------------------+----------+----------+-------------------------------------------------------+
100-
| PROP_INVALIDATE | -1 | bool | Invalidate |
101-
+---------------------------------------+----------+----------+-------------------------------------------------------+
102102

103103
Query entity
104104
------------

0 commit comments

Comments
 (0)