IGNITE-14850 Add documentation to transaction's api - Fixes #41.
diff --git a/docs/async_examples.rst b/docs/async_examples.rst
index 4bc21ae..322869c 100644
--- a/docs/async_examples.rst
+++ b/docs/async_examples.rst
@@ -78,6 +78,50 @@
:dedent: 12
:lines: 96-105
+Transactions
+------------
+File: `transactions.py`_.
+
+Client transactions are supported for caches with
+:py:attr:`~pyignite.datatypes.cache_config.CacheAtomicityMode.TRANSACTIONAL` mode.
+
+Let's create transactional cache:
+
+.. literalinclude:: ../examples/transactions.py
+ :language: python
+ :dedent: 8
+ :lines: 29-32
+
+Let's start a transaction and commit it:
+
+.. literalinclude:: ../examples/transactions.py
+ :language: python
+ :dedent: 8
+ :lines: 35-40
+
+Let's check that the transaction was committed successfully:
+
+.. literalinclude:: ../examples/transactions.py
+ :language: python
+ :dedent: 8
+ :lines: 42-44
+
+Let's check that raising exception inside `async with` block leads to transaction's rollback
+
+.. literalinclude:: ../examples/transactions.py
+ :language: python
+ :dedent: 8
+ :lines: 47-58
+
+Let's check that timed out transaction is successfully rolled back
+
+.. literalinclude:: ../examples/transactions.py
+ :language: python
+ :dedent: 8
+ :lines: 61-72
+
+See more info about transaction's parameters in a documentation of :py:meth:`~pyignite.aio_client.AioClient.tx_start`
+
SQL
---
File: `async_sql.py`_.
@@ -173,4 +217,5 @@
.. _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
\ No newline at end of file
+.. _async_sql.py: https://github.com/apache/ignite-python-thin-client/blob/master/examples/async_sql.py
+.. _transactions.py: https://github.com/apache/ignite-python-thin-client/blob/master/examples/transactions.py
\ No newline at end of file
diff --git a/docs/datatypes/cache_props.rst b/docs/datatypes/cache_props.rst
index 380ccf2..77d50f7 100644
--- a/docs/datatypes/cache_props.rst
+++ b/docs/datatypes/cache_props.rst
@@ -22,7 +22,7 @@
The :mod:`~pyignite.datatypes.prop_codes` module contains a list of ordinal
values, that represent various cache settings.
-Please refer to the `Apache Ignite Data Grid`_ documentation on cache
+Please refer to the `Configuring Caches`_ documentation on cache
synchronization, rebalance, affinity and other cache configuration-related
matters.
@@ -160,7 +160,7 @@
- `type_name`: name of the complex object,
- `affinity_key_field_name`: name of the affinity key field.
-.. _Apache Ignite Data Grid: https://apacheignite.readme.io/docs/data-grid
+.. _Configuring Caches: https://ignite.apache.org/docs/latest/configuring-caches/configuration-overview.html
Expiry policy
-------------
diff --git a/docs/datatypes/parsers.rst b/docs/datatypes/parsers.rst
index 92329cc..06ce659 100644
--- a/docs/datatypes/parsers.rst
+++ b/docs/datatypes/parsers.rst
@@ -136,40 +136,40 @@
|0x1b |`Wrapped data`_ |tuple[int, bytes] |:class:`~pyignite.datatypes.complex.WrappedDataObject` |
+-------------+--------------------+-------------------------------+------------------------------------------------------------------+
-.. _Byte: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-byte
-.. _Short: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-short
-.. _Int: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-int
-.. _Long: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-long
-.. _Float: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-float
-.. _Double: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-double
-.. _Char: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-char
-.. _Bool: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-bool
-.. _Null: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-null
-.. _String: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-string
-.. _UUID: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-uuid-guid-
-.. _Timestamp: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-timestamp
-.. _Date: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-date
-.. _Time: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-time
-.. _Decimal: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-decimal
-.. _Enum: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-enum
-.. _Byte array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-byte-array
-.. _Short array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-short-array
-.. _Int array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-int-array
-.. _Long array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-long-array
-.. _Float array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-float-array
-.. _Double array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-double-array
-.. _Char array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-char-array
-.. _Bool array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-bool-array
-.. _String array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-string-array
-.. _UUID array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-uuid-guid-array
-.. _Timestamp array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-timestamp-array
-.. _Date array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-date-array
-.. _Time array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-time-array
-.. _Decimal array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-decimal-array
-.. _Object array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-object-collections
-.. _Collection: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-collection
-.. _Map: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-map
-.. _Enum array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-enum-array
-.. _Binary enum: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-binary-enum
-.. _Wrapped data: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-wrapped-data
-.. _Complex object: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-complex-object
+.. _Byte: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#byte
+.. _Short: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#short
+.. _Int: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#int
+.. _Long: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#long
+.. _Float: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#float
+.. _Double: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#double
+.. _Char: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#char
+.. _Bool: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#bool
+.. _Null: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#null
+.. _String: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#string
+.. _UUID: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#uuid-guid
+.. _Timestamp: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#timestamp
+.. _Date: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#date
+.. _Time: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#time
+.. _Decimal: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#decimal
+.. _Enum: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#enum
+.. _Byte array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#byte-array
+.. _Short array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#short-array
+.. _Int array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#int-array
+.. _Long array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#long-array
+.. _Float array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#float-array
+.. _Double array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#double-array
+.. _Char array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#char-array
+.. _Bool array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#bool-array
+.. _String array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#string-array
+.. _UUID array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#uuid-guid-array
+.. _Timestamp array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#timestamp-array
+.. _Date array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#date-array
+.. _Time array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#time-array
+.. _Decimal array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#decimal-array
+.. _Object array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#object-collections
+.. _Collection: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#collection
+.. _Map: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#map
+.. _Enum array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#enum-array
+.. _Binary enum: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#binary-enum
+.. _Wrapped data: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#wrapped-data
+.. _Complex object: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#complex-object
diff --git a/docs/examples.rst b/docs/examples.rst
index 07ec65c..97facdb 100644
--- a/docs/examples.rst
+++ b/docs/examples.rst
@@ -206,6 +206,51 @@
:dedent: 4
:lines: 56-65
+
+Transactions
+------------
+File: `transactions.py`_.
+
+Client transactions are supported for caches with
+:py:attr:`~pyignite.datatypes.cache_config.CacheAtomicityMode.TRANSACTIONAL` mode.
+
+Let's create transactional cache:
+
+.. literalinclude:: ../examples/transactions.py
+ :language: python
+ :dedent: 8
+ :lines: 81-84
+
+Let's start a transaction and commit it:
+
+.. literalinclude:: ../examples/transactions.py
+ :language: python
+ :dedent: 8
+ :lines: 87-91
+
+Let's check that the transaction was committed successfully:
+
+.. literalinclude:: ../examples/transactions.py
+ :language: python
+ :dedent: 8
+ :lines: 93-94
+
+Let's check that raising exception inside `with` block leads to transaction's rollback
+
+.. literalinclude:: ../examples/transactions.py
+ :language: python
+ :dedent: 8
+ :lines: 97-107
+
+Let's check that timed out transaction is successfully rolled back
+
+.. literalinclude:: ../examples/transactions.py
+ :language: python
+ :dedent: 8
+ :lines: 110-120
+
+See more info about transaction's parameters in a documentation of :py:meth:`~pyignite.client.Client.tx_start`
+
SQL
---
File: `sql.py`_.
@@ -717,6 +762,7 @@
.. _read_binary.py: https://github.com/apache/ignite-python-thin-client/blob/master/examples/read_binary.py
.. _create_binary.py: https://github.com/apache/ignite-python-thin-client/blob/master/examples/create_binary.py
.. _migrate_binary.py: https://github.com/apache/ignite-python-thin-client/blob/master/examples/migrate_binary.py
+.. _transactions.py: https://github.com/apache/ignite-python-thin-client/blob/master/examples/transactions.py
.. _Getting Started: https://ignite.apache.org/docs/latest/thin-clients/python-thin-client
.. _PyIgnite GitHub repository: https://github.com/apache/ignite-python-thin-client/blob/master
.. _Complex object: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#complex-object
diff --git a/docs/readme.rst b/docs/readme.rst
index 807865a..5fc76a7 100644
--- a/docs/readme.rst
+++ b/docs/readme.rst
@@ -181,8 +181,8 @@
This is a free software, brought to you on terms of the `Apache License v2`_.
-.. _Apache Ignite: https://apacheignite.readme.io/docs/what-is-ignite
-.. _binary client protocol: https://apacheignite.readme.io/docs/binary-client-protocol
+.. _Apache Ignite: https://ignite.apache.org
+.. _binary client protocol: https://ignite.apache.org/docs/latest/binary-client-protocol/binary-client-protocol
.. _Apache License v2: http://www.apache.org/licenses/LICENSE-2.0
.. _virtualenv: https://virtualenv.pypa.io/
.. _tox: https://tox.readthedocs.io/en/latest/
diff --git a/examples/transactions.py b/examples/transactions.py
new file mode 100644
index 0000000..895837c
--- /dev/null
+++ b/examples/transactions.py
@@ -0,0 +1,134 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# 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 pyignite import AioClient, Client
+from pyignite.datatypes import TransactionIsolation, TransactionConcurrency
+from pyignite.datatypes.prop_codes import PROP_CACHE_ATOMICITY_MODE, PROP_NAME
+from pyignite.datatypes.cache_config import CacheAtomicityMode
+from pyignite.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(1)
+ 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())
diff --git a/tests/common/test_transactions.py b/tests/common/test_transactions.py
index 0cfa46a..f4efba5 100644
--- a/tests/common/test_transactions.py
+++ b/tests/common/test_transactions.py
@@ -67,6 +67,7 @@
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()
@@ -77,6 +78,7 @@
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()
