Skip to content

Commit a53afcc

Browse files
ivandaschivandasch
committed
IGNITE-14850 Add documentation to transaction's api - Fixes #41.
1 parent 9945ecb commit a53afcc

File tree

7 files changed

+269
-42
lines changed

7 files changed

+269
-42
lines changed

‎docs/async_examples.rst‎

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,50 @@ Secondly, expiry policy can be set for all cache operations, which are done unde
7878
:dedent: 12
7979
:lines: 96-105
8080

81+
Transactions
82+
------------
83+
File: `transactions.py`_.
84+
85+
Client transactions are supported for caches with
86+
:py:attr:`~pyignite.datatypes.cache_config.CacheAtomicityMode.TRANSACTIONAL` mode.
87+
88+
Let's create transactional cache:
89+
90+
.. literalinclude:: ../examples/transactions.py
91+
:language: python
92+
:dedent: 8
93+
:lines: 29-32
94+
95+
Let's start a transaction and commit it:
96+
97+
.. literalinclude:: ../examples/transactions.py
98+
:language: python
99+
:dedent: 8
100+
:lines: 35-40
101+
102+
Let's check that the transaction was committed successfully:
103+
104+
.. literalinclude:: ../examples/transactions.py
105+
:language: python
106+
:dedent: 8
107+
:lines: 42-44
108+
109+
Let's check that raising exception inside `async with` block leads to transaction's rollback
110+
111+
.. literalinclude:: ../examples/transactions.py
112+
:language: python
113+
:dedent: 8
114+
:lines: 47-58
115+
116+
Let's check that timed out transaction is successfully rolled back
117+
118+
.. literalinclude:: ../examples/transactions.py
119+
:language: python
120+
:dedent: 8
121+
:lines: 61-72
122+
123+
See more info about transaction's parameters in a documentation of :py:meth:`~pyignite.aio_client.AioClient.tx_start`
124+
81125
SQL
82126
---
83127
File: `async_sql.py`_.
@@ -173,4 +217,5 @@ Finally, delete the tables used in this example with the following queries:
173217

174218
.. _expiry_policy.py: https://github.com/apache/ignite-python-thin-client/blob/master/examples/expiry_policy.py
175219
.. _async_key_value.py: https://github.com/apache/ignite-python-thin-client/blob/master/examples/async_key_value.py
176-
.. _async_sql.py: https://github.com/apache/ignite-python-thin-client/blob/master/examples/async_sql.py
220+
.. _async_sql.py: https://github.com/apache/ignite-python-thin-client/blob/master/examples/async_sql.py
221+
.. _transactions.py: https://github.com/apache/ignite-python-thin-client/blob/master/examples/transactions.py

‎docs/datatypes/cache_props.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ Cache Properties
2222
The :mod:`~pyignite.datatypes.prop_codes` module contains a list of ordinal
2323
values, that represent various cache settings.
2424

25-
Please refer to the `Apache Ignite Data Grid`_ documentation on cache
25+
Please refer to the `Configuring Caches`_ documentation on cache
2626
synchronization, rebalance, affinity and other cache configuration-related
2727
matters.
2828

@@ -160,7 +160,7 @@ A dict of the following format:
160160
- `type_name`: name of the complex object,
161161
- `affinity_key_field_name`: name of the affinity key field.
162162

163-
.. _Apache Ignite Data Grid: https://apacheignite.readme.io/docs/data-grid
163+
.. _Configuring Caches: https://ignite.apache.org/docs/latest/configuring-caches/configuration-overview.html
164164

165165
Expiry policy
166166
-------------

‎docs/datatypes/parsers.rst‎

Lines changed: 37 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -136,40 +136,40 @@ with your data, in to some API function as a *type conversion hint*.
136136
|0x1b |`Wrapped data`_ |tuple[int, bytes] |:class:`~pyignite.datatypes.complex.WrappedDataObject` |
137137
+-------------+--------------------+-------------------------------+------------------------------------------------------------------+
138138

139-
.. _Byte: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-byte
140-
.. _Short: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-short
141-
.. _Int: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-int
142-
.. _Long: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-long
143-
.. _Float: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-float
144-
.. _Double: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-double
145-
.. _Char: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-char
146-
.. _Bool: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-bool
147-
.. _Null: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-null
148-
.. _String: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-string
149-
.. _UUID: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-uuid-guid-
150-
.. _Timestamp: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-timestamp
151-
.. _Date: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-date
152-
.. _Time: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-time
153-
.. _Decimal: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-decimal
154-
.. _Enum: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-enum
155-
.. _Byte array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-byte-array
156-
.. _Short array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-short-array
157-
.. _Int array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-int-array
158-
.. _Long array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-long-array
159-
.. _Float array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-float-array
160-
.. _Double array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-double-array
161-
.. _Char array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-char-array
162-
.. _Bool array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-bool-array
163-
.. _String array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-string-array
164-
.. _UUID array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-uuid-guid-array
165-
.. _Timestamp array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-timestamp-array
166-
.. _Date array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-date-array
167-
.. _Time array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-time-array
168-
.. _Decimal array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-decimal-array
169-
.. _Object array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-object-collections
170-
.. _Collection: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-collection
171-
.. _Map: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-map
172-
.. _Enum array: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-enum-array
173-
.. _Binary enum: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-binary-enum
174-
.. _Wrapped data: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-wrapped-data
175-
.. _Complex object: https://apacheignite.readme.io/docs/binary-client-protocol-data-format#section-complex-object
139+
.. _Byte: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#byte
140+
.. _Short: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#short
141+
.. _Int: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#int
142+
.. _Long: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#long
143+
.. _Float: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#float
144+
.. _Double: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#double
145+
.. _Char: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#char
146+
.. _Bool: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#bool
147+
.. _Null: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#null
148+
.. _String: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#string
149+
.. _UUID: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#uuid-guid
150+
.. _Timestamp: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#timestamp
151+
.. _Date: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#date
152+
.. _Time: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#time
153+
.. _Decimal: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#decimal
154+
.. _Enum: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#enum
155+
.. _Byte array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#byte-array
156+
.. _Short array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#short-array
157+
.. _Int array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#int-array
158+
.. _Long array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#long-array
159+
.. _Float array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#float-array
160+
.. _Double array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#double-array
161+
.. _Char array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#char-array
162+
.. _Bool array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#bool-array
163+
.. _String array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#string-array
164+
.. _UUID array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#uuid-guid-array
165+
.. _Timestamp array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#timestamp-array
166+
.. _Date array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#date-array
167+
.. _Time array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#time-array
168+
.. _Decimal array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#decimal-array
169+
.. _Object array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#object-collections
170+
.. _Collection: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#collection
171+
.. _Map: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#map
172+
.. _Enum array: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#enum-array
173+
.. _Binary enum: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#binary-enum
174+
.. _Wrapped data: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#wrapped-data
175+
.. _Complex object: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#complex-object

‎docs/examples.rst‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -206,6 +206,51 @@ contents. But it still can be used for interoperability with Java.
206206
:dedent: 4
207207
:lines: 56-65
208208

209+
210+
Transactions
211+
------------
212+
File: `transactions.py`_.
213+
214+
Client transactions are supported for caches with
215+
:py:attr:`~pyignite.datatypes.cache_config.CacheAtomicityMode.TRANSACTIONAL` mode.
216+
217+
Let's create transactional cache:
218+
219+
.. literalinclude:: ../examples/transactions.py
220+
:language: python
221+
:dedent: 8
222+
:lines: 81-84
223+
224+
Let's start a transaction and commit it:
225+
226+
.. literalinclude:: ../examples/transactions.py
227+
:language: python
228+
:dedent: 8
229+
:lines: 87-91
230+
231+
Let's check that the transaction was committed successfully:
232+
233+
.. literalinclude:: ../examples/transactions.py
234+
:language: python
235+
:dedent: 8
236+
:lines: 93-94
237+
238+
Let's check that raising exception inside `with` block leads to transaction's rollback
239+
240+
.. literalinclude:: ../examples/transactions.py
241+
:language: python
242+
:dedent: 8
243+
:lines: 97-107
244+
245+
Let's check that timed out transaction is successfully rolled back
246+
247+
.. literalinclude:: ../examples/transactions.py
248+
:language: python
249+
:dedent: 8
250+
:lines: 110-120
251+
252+
See more info about transaction's parameters in a documentation of :py:meth:`~pyignite.client.Client.tx_start`
253+
209254
SQL
210255
---
211256
File: `sql.py`_.
@@ -717,6 +762,7 @@ with the following message:
717762
.. _read_binary.py: https://github.com/apache/ignite-python-thin-client/blob/master/examples/read_binary.py
718763
.. _create_binary.py: https://github.com/apache/ignite-python-thin-client/blob/master/examples/create_binary.py
719764
.. _migrate_binary.py: https://github.com/apache/ignite-python-thin-client/blob/master/examples/migrate_binary.py
765+
.. _transactions.py: https://github.com/apache/ignite-python-thin-client/blob/master/examples/transactions.py
720766
.. _Getting Started: https://ignite.apache.org/docs/latest/thin-clients/python-thin-client
721767
.. _PyIgnite GitHub repository: https://github.com/apache/ignite-python-thin-client/blob/master
722768
.. _Complex object: https://ignite.apache.org/docs/latest/binary-client-protocol/data-format#complex-object

‎docs/readme.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -181,8 +181,8 @@ Licensing
181181

182182
This is a free software, brought to you on terms of the `Apache License v2`_.
183183

184-
.. _Apache Ignite: https://apacheignite.readme.io/docs/what-is-ignite
185-
.. _binary client protocol: https://apacheignite.readme.io/docs/binary-client-protocol
184+
.. _Apache Ignite: https://ignite.apache.org
185+
.. _binary client protocol: https://ignite.apache.org/docs/latest/binary-client-protocol/binary-client-protocol
186186
.. _Apache License v2: http://www.apache.org/licenses/LICENSE-2.0
187187
.. _virtualenv: https://virtualenv.pypa.io/
188188
.. _tox: https://tox.readthedocs.io/en/latest/

‎examples/transactions.py‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Licensed to the Apache Software Foundation (ASF) under one or more
2+
# contributor license agreements. See the NOTICE file distributed with
3+
# this work for additional information regarding copyright ownership.
4+
# The ASF licenses this file to You under the Apache License, Version 2.0
5+
# (the "License"); you may not use this file except in compliance with
6+
# the License. You may obtain a copy of the License at
7+
#
8+
# http://www.apache.org/licenses/LICENSE-2.0
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+
import asyncio
17+
import sys
18+
import time
19+
20+
from pyignite import AioClient, Client
21+
from pyignite.datatypes import TransactionIsolation, TransactionConcurrency
22+
from pyignite.datatypes.prop_codes import PROP_CACHE_ATOMICITY_MODE, PROP_NAME
23+
from pyignite.datatypes.cache_config import CacheAtomicityMode
24+
from pyignite.exceptions import CacheError
25+
26+
27+
async def async_example():
28+
client = AioClient()
29+
async with client.connect('127.0.0.1', 10800):
30+
cache = await client.get_or_create_cache({
31+
PROP_NAME: 'tx_cache',
32+
PROP_CACHE_ATOMICITY_MODE: CacheAtomicityMode.TRANSACTIONAL
33+
})
34+
35+
# starting transaction
36+
key = 1
37+
async with client.tx_start(
38+
isolation=TransactionIsolation.REPEATABLE_READ, concurrency=TransactionConcurrency.PESSIMISTIC
39+
) as tx:
40+
await cache.put(key, 'success')
41+
await tx.commit()
42+
43+
# key=1 value=success
44+
val = await cache.get(key)
45+
print(f"key=1 value={val}")
46+
47+
# rollback transaction.
48+
try:
49+
async with client.tx_start(
50+
isolation=TransactionIsolation.REPEATABLE_READ, concurrency=TransactionConcurrency.PESSIMISTIC
51+
):
52+
await cache.put(key, 'fail')
53+
raise RuntimeError('test')
54+
except RuntimeError:
55+
pass
56+
57+
# key=1 value=success
58+
val = await cache.get(key)
59+
print(f"key=1 value={val}")
60+
61+
# rollback transaction on timeout.
62+
try:
63+
async with client.tx_start(timeout=1.0, label='long-tx') as tx:
64+
await cache.put(key, 'fail')
65+
await asyncio.sleep(2.0)
66+
await tx.commit()
67+
except CacheError as e:
68+
# Cache transaction timed out: GridNearTxLocal[...timeout=1000, ... label=long-tx]
69+
print(e)
70+
71+
# key=1 value=success
72+
val = await cache.get(1)
73+
print(f"key=1 value={val}")
74+
75+
# destroy cache
76+
await cache.destroy()
77+
78+
79+
def sync_example():
80+
client = Client()
81+
with client.connect('127.0.0.1', 10800):
82+
cache = client.get_or_create_cache({
83+
PROP_NAME: 'tx_cache',
84+
PROP_CACHE_ATOMICITY_MODE: CacheAtomicityMode.TRANSACTIONAL
85+
})
86+
87+
# starting transaction
88+
with client.tx_start(
89+
isolation=TransactionIsolation.REPEATABLE_READ, concurrency=TransactionConcurrency.PESSIMISTIC
90+
) as tx:
91+
cache.put(1, 'success')
92+
tx.commit()
93+
94+
# key=1 value=success
95+
print(f"key=1 value={cache.get(1)}")
96+
97+
# rollback transaction.
98+
try:
99+
with client.tx_start(
100+
isolation=TransactionIsolation.REPEATABLE_READ, concurrency=TransactionConcurrency.PESSIMISTIC
101+
):
102+
cache.put(1, 'fail')
103+
raise RuntimeError('test')
104+
except RuntimeError:
105+
pass
106+
107+
# key=1 value=success
108+
print(f"key=1 value={cache.get(1)}")
109+
110+
# rollback transaction on timeout.
111+
try:
112+
with client.tx_start(timeout=1.0, label='long-tx') as tx:
113+
cache.put(1, 'fail')
114+
time.sleep(2.0)
115+
tx.commit()
116+
except CacheError as e:
117+
# Cache transaction timed out: GridNearTxLocal[...timeout=1000, ... label=long-tx]
118+
print(e)
119+
120+
# key=1 value=success
121+
print(f"key=1 value={cache.get(1)}")
122+
123+
# destroy cache
124+
cache.destroy()
125+
126+
127+
if __name__ == '__main__':
128+
print("Starting sync example")
129+
sync_example()
130+
131+
if sys.version_info >= (3, 7):
132+
print("Starting async example")
133+
loop = asyncio.get_event_loop()
134+
loop.run_until_complete(async_example())

‎tests/common/test_transactions.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@ def tx_cache(client):
6767
PROP_NAME: 'tx_cache',
6868
PROP_CACHE_ATOMICITY_MODE: CacheAtomicityMode.TRANSACTIONAL
6969
})
70+
time.sleep(1.0) # Need to sleep because of https://issues.apache.org/jira/browse/IGNITE-14868
7071
yield cache
7172
cache.destroy()
7273

@@ -77,6 +78,7 @@ async def async_tx_cache(async_client):
7778
PROP_NAME: 'tx_cache',
7879
PROP_CACHE_ATOMICITY_MODE: CacheAtomicityMode.TRANSACTIONAL
7980
})
81+
await asyncio.sleep(1.0) # Need to sleep because of https://issues.apache.org/jira/browse/IGNITE-14868
8082
yield cache
8183
await cache.destroy()
8284

0 commit comments

Comments
 (0)