GG-33875 [IGNITE-14850] Document Transactions API (#50)

(cherry picked from commit a53afcc)
(cherry picked from commit 0afab5b)
(cherry picked from commit c64fb10)

Co-authored-by: Ivan Daschinsky <[email protected]>

Author: isapego

docs/async_examples.rst

@@ -77,6 +77,50 @@ Secondly, expiry policy can be set for all cache operations, which are done unde
   :dedent: 12
   :lines: 96-105
 
+Transactions
+------------
+File: `transactions.py`_.
+
+Client transactions are supported for caches with
+:py:attr:`~pygridgain.datatypes.cache_config.CacheAtomicityMode.TRANSACTIONAL` mode.
+
+Let's create transactional cache:
+
+.. literalinclude:: ../examples/transactions.py
+  :language: python
+  :dedent: 8
+  :lines: 30-33
+
+Let's start a transaction and commit it:
+
+.. literalinclude:: ../examples/transactions.py
+  :language: python
+  :dedent: 8
+  :lines: 36-41
+
+Let's check that the transaction was committed successfully:
+
+.. literalinclude:: ../examples/transactions.py
+  :language: python
+  :dedent: 8
+  :lines: 44-45
+
+Let's check that raising exception inside `async with` block leads to transaction's rollback
+
+.. literalinclude:: ../examples/transactions.py
+  :language: python
+  :dedent: 8
+  :lines: 48-59
+
+Let's check that timed out transaction is successfully rolled back
+
+.. literalinclude:: ../examples/transactions.py
+  :language: python
+  :dedent: 8
+  :lines: 62-73
+
+See more info about transaction's parameters in a documentation of :py:meth:`~pygridgain.aio_client.AioClient.tx_start`
+
 SQL
 ---
 File: `async_sql.py`_.
@@ -170,6 +214,7 @@ Finally, delete the tables used in this example with the following queries:
 
 
 
-.. _expiry_policy.py: https://github.com/apache/ignite-python-thin-client/blob/master/examples/expiry_policy.py
-.. _async_key_value.py: https://github.com/apache/ignite-python-thin-client/blob/master/examples/async_key_value.py
-.. _async_sql.py: https://github.com/apache/ignite-python-thin-client/blob/master/examples/async_sql.py
+.. _expiry_policy.py: https://github.com/gridgain/python-thin-client/blob/master/examples/expiry_policy.py
+.. _async_key_value.py: https://github.com/gridgain/python-thin-client/blob/master/examples/async_key_value.py
+.. _async_sql.py: https://github.com/gridgain/python-thin-client/blob/master/examples/async_sql.py
+.. _transactions.py: https://github.com/gridgain/python-thin-client/blob/master/examples/transactions.py

docs/datatypes/cache_props.rst

@@ -21,7 +21,7 @@ Cache Properties
 The :mod:`~pygridgain.datatypes.prop_codes` module contains a list of ordinal
 values, that represent various cache settings.
 
-Please refer to the `GridGain Data Grid`_ documentation on cache
+Please refer to the `Configuring Caches`_ documentation on cache
 synchronization, rebalance, affinity and other cache configuration-related
 matters.
 
@@ -161,10 +161,10 @@ A dict of the following format:
 - `type_name`: name of the complex object,
 - `affinity_key_field_name`: name of the affinity key field.
 
-.. _GridGain Data Grid: https://www.gridgain.com/technology/in-memory-computing-platform/data-grid
+.. _Configuring Caches: https://www.gridgain.com/docs/latest/configuring-caches/configuration-overview.html
 
 Expiry policy
--------------
+-------------https://www.gridgain.com/docs/latest/developers-guide/configuring-caches/configuration-overview
 
 Set expiry policy to cache (see :py:class:`~pygridgain.datatypes.expiry_policy.ExpiryPolicy`). If set to `None`,
 expiry policy will not be set.

docs/examples.rst

@@ -205,6 +205,51 @@ contents. But it still can be used for interoperability with Java.
   :dedent: 4
   :lines: 56-65
 
+
+Transactions
+------------
+File: `transactions.py`_.
+
+Client transactions are supported for caches with
+:py:attr:`~pygridgain.datatypes.cache_config.CacheAtomicityMode.TRANSACTIONAL` mode.
+
+Let's create transactional cache:
+
+.. literalinclude:: ../examples/transactions.py
+  :language: python
+  :dedent: 8
+  :lines: 82-85
+
+Let's start a transaction and commit it:
+
+.. literalinclude:: ../examples/transactions.py
+  :language: python
+  :dedent: 8
+  :lines: 88-92
+
+Let's check that the transaction was committed successfully:
+
+.. literalinclude:: ../examples/transactions.py
+  :language: python
+  :dedent: 8
+  :lines: 94-95
+
+Let's check that raising exception inside `with` block leads to transaction's rollback
+
+.. literalinclude:: ../examples/transactions.py
+  :language: python
+  :dedent: 8
+  :lines: 98-108
+
+Let's check that timed out transaction is successfully rolled back
+
+.. literalinclude:: ../examples/transactions.py
+  :language: python
+  :dedent: 8
+  :lines: 111-121
+
+See more info about transaction's parameters in a documentation of :py:meth:`~pygridgain.client.Client.tx_start`
+
 SQL
 ---
 File: `sql.py`_.
@@ -705,26 +750,26 @@ with the following message:
     # pygridgain.exceptions.HandshakeError: Handshake error: Unauthenticated sessions are prohibited.
 
 .. _get_and_put.py: https://github.com/gridgain/python-thin-client/tree/master/examples/get_and_put.py
-.. _async_key_value.py: https://github.com/apache/ignite-python-thin-client/blob/master/examples/async_key_value.py
+.. _async_key_value.py: https://github.com/gridgain/python-thin-client/blob/master/examples/async_key_value.py
 .. _type_hints.py: https://github.com/gridgain/python-thin-client/tree/master/examples/type_hints.py
 .. _failover.py: https://github.com/gridgain/python-thin-client/tree/master/examples/failover.py
 .. _scans.py: https://github.com/gridgain/python-thin-client/tree/master/examples/scans.py
-.. _expiry_policy.py: https://github.com/apache/ignite-python-thin-client/blob/master/examples/expiry_policy.py
+.. _expiry_policy.py: https://github.com/gridgain/python-thin-client/blob/master/examples/expiry_policy.py
 .. _sql.py: https://github.com/gridgain/python-thin-client/tree/master/examples/sql.py
-.. _async_sql.py: https://github.com/apache/ignite-python-thin-client/blob/master/examples/async_sql.py
+.. _async_sql.py: https://github.com/gridgain/python-thin-client/blob/master/examples/async_sql.py
 .. _binary_basics.py: https://github.com/gridgain/python-thin-client/tree/master/examples/binary_basics.py
 .. _read_binary.py: https://github.com/gridgain/python-thin-client/tree/master/examples/read_binary.py
 .. _create_binary.py: https://github.com/gridgain/python-thin-client/tree/master/examples/create_binary.py
 .. _migrate_binary.py: https://github.com/gridgain/python-thin-client/tree/master/examples/migrate_binary.py
-.. _Getting Started: https://ignite.apache.org/docs/latest/quick-start/sql
+.. _transactions.py: https://github.com/gridgain/python-thin-client/blob/master/examples/transactions.py
+.. _Getting Started: https://www.gridgain.com/docs/latest/getting-started/quick-start/sql
 .. _GridGain CE GitHub repository: https://github.com/gridgain/gridgain/blob/master/examples/sql/world.sql
 .. _Complex object: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#complex-object
 .. _Java keytool: https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html
-.. _Securing Connection Between Nodes: https://ignite.apache.org/docs/latest/security/ssl-tls#ssltls-for-nodes
+.. _Securing Connection Between Nodes: https://www.gridgain.com/docs/latest/administrators-guide/security/ssl-tls#ssltls-for-nodes
 .. _ClientConnectorConfiguration: https://www.gridgain.com/sdk/latest/javadoc/org/apache/ignite/configuration/ClientConnectorConfiguration.html
 .. _openssl: https://www.openssl.org/docs/manmaster/man1/openssl.html
-.. _Authentication: https://ignite.apache.org/docs/latest/security/authentication
+.. _Authentication: https://www.gridgain.com/docs/latest/administrators-guide/security/authentication
 .. _attrs: https://pypi.org/project/attrs/
 .. _get_and_put_complex.py: https://github.com/gridgain/python-thin-client/tree/master/examples/get_and_put_complex.py
 .. _Collection: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#collection
-.. _simple class names: https://ignite.apache.org/docs/latest/data-modeling/binary-marshaller#binary-name-mapper-and-binary-id-mapper

examples/transactions.py

@@ -0,0 +1,134 @@
+#
+# Copyright 2021 GridGain Systems, Inc. and Contributors.
+#
+# Licensed under the GridGain Community Edition License (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.gridgain.com/products/software/community-edition/gridgain-community-edition-license
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+import asyncio
+import sys
+import time
+
+from pygridgain import AioClient, Client
+from pygridgain.datatypes import TransactionIsolation, TransactionConcurrency
+from pygridgain.datatypes.prop_codes import PROP_CACHE_ATOMICITY_MODE, PROP_NAME
+from pygridgain.datatypes.cache_config import CacheAtomicityMode
+from pygridgain.exceptions import CacheError
+
+
+async def async_example():
+    client = AioClient()
+    async with client.connect('127.0.0.1', 10800):
+        cache = await client.get_or_create_cache({
+            PROP_NAME: 'tx_cache',
+            PROP_CACHE_ATOMICITY_MODE: CacheAtomicityMode.TRANSACTIONAL
+        })
+
+        # starting transaction
+        key = 1
+        async with client.tx_start(
+                isolation=TransactionIsolation.REPEATABLE_READ, concurrency=TransactionConcurrency.PESSIMISTIC
+        ) as tx:
+            await cache.put(key, 'success')
+            await tx.commit()
+
+        # key=1 value=success
+        val = await cache.get(key)
+        print(f"key=1 value={val}")
+
+        # rollback transaction.
+        try:
+            async with client.tx_start(
+                    isolation=TransactionIsolation.REPEATABLE_READ, concurrency=TransactionConcurrency.PESSIMISTIC
+            ):
+                await cache.put(key, 'fail')
+                raise RuntimeError('test')
+        except RuntimeError:
+            pass
+
+        # key=1 value=success
+        val = await cache.get(key)
+        print(f"key=1 value={val}")
+
+        # rollback transaction on timeout.
+        try:
+            async with client.tx_start(timeout=1.0, label='long-tx') as tx:
+                await cache.put(key, 'fail')
+                await asyncio.sleep(2.0)
+                await tx.commit()
+        except CacheError as e:
+            # Cache transaction timed out: GridNearTxLocal[...timeout=1000, ... label=long-tx]
+            print(e)
+
+        # key=1 value=success
+        val = await cache.get(key)
+        print(f"key=1 value={val}")
+
+        # destroy cache
+        await cache.destroy()
+
+
+def sync_example():
+    client = Client()
+    with client.connect('127.0.0.1', 10800):
+        cache = client.get_or_create_cache({
+            PROP_NAME: 'tx_cache',
+            PROP_CACHE_ATOMICITY_MODE: CacheAtomicityMode.TRANSACTIONAL
+        })
+
+        # starting transaction
+        with client.tx_start(
+                isolation=TransactionIsolation.REPEATABLE_READ, concurrency=TransactionConcurrency.PESSIMISTIC
+        ) as tx:
+            cache.put(1, 'success')
+            tx.commit()
+
+        # key=1 value=success
+        print(f"key=1 value={cache.get(1)}")
+
+        # rollback transaction.
+        try:
+            with client.tx_start(
+                    isolation=TransactionIsolation.REPEATABLE_READ, concurrency=TransactionConcurrency.PESSIMISTIC
+            ):
+                cache.put(1, 'fail')
+                raise RuntimeError('test')
+        except RuntimeError:
+            pass
+
+        # key=1 value=success
+        print(f"key=1 value={cache.get(1)}")
+
+        # rollback transaction on timeout.
+        try:
+            with client.tx_start(timeout=1.0, label='long-tx') as tx:
+                cache.put(1, 'fail')
+                time.sleep(2.0)
+                tx.commit()
+        except CacheError as e:
+            # Cache transaction timed out: GridNearTxLocal[...timeout=1000, ... label=long-tx]
+            print(e)
+
+        # key=1 value=success
+        print(f"key=1 value={cache.get(1)}")
+
+        # destroy cache
+        cache.destroy()
+
+
+if __name__ == '__main__':
+    print("Starting sync example")
+    sync_example()
+
+    if sys.version_info >= (3, 7):
+        print("Starting async example")
+        loop = asyncio.get_event_loop()
+        loop.run_until_complete(async_example())

tests/common/test_transactions.py

@@ -68,6 +68,7 @@ def tx_cache(client):
         PROP_NAME: 'tx_cache',
         PROP_CACHE_ATOMICITY_MODE: CacheAtomicityMode.TRANSACTIONAL
     })
+    time.sleep(1.0)  # Need to sleep because of https://issues.apache.org/jira/browse/IGNITE-14868
     yield cache
     cache.destroy()
 
@@ -78,6 +79,7 @@ async def async_tx_cache(async_client):
         PROP_NAME: 'tx_cache',
         PROP_CACHE_ATOMICITY_MODE: CacheAtomicityMode.TRANSACTIONAL
     })
+    await asyncio.sleep(1.0)  # Need to sleep because of https://issues.apache.org/jira/browse/IGNITE-14868
     yield cache
     await cache.destroy()