kurrentdbclient 1.2.2__tar.gz → 1.2.3__tar.gz

{kurrentdbclient-1.2.2 → kurrentdbclient-1.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kurrentdbclient
-Version: 1.2.2
+Version: 1.2.3
 Summary: Python gRPC Client for KurrentDB
 License: BSD-3-Clause
 License-File: LICENSE
@@ -21,8 +21,8 @@ Requires-Dist: googleapis-common-protos
 Requires-Dist: grpcio-status
 Requires-Dist: grpcio[protobuf] (>=1.75.1,<2.0)
 Requires-Dist: opentelemetry-api (>=1.28.0,<2.0) ; extra == "opentelemetry"
-Requires-Dist: opentelemetry-instrumentation (>=0.49b0) ; extra == "opentelemetry"
-Requires-Dist: opentelemetry-semantic-conventions (>=0.49b0) ; extra == "opentelemetry"
+Requires-Dist: opentelemetry-instrumentation (>=0.62b1) ; extra == "opentelemetry"
+Requires-Dist: opentelemetry-semantic-conventions (>=0.62b1) ; extra == "opentelemetry"
 Requires-Dist: typing_extensions
 Project-URL: Homepage, https://github.com/pyeventsourcing/kurrentdbclient
 Project-URL: Repository, https://github.com/pyeventsourcing/kurrentdbclient
@@ -52,9 +52,10 @@ with the KurrentDB team, and are officially supported by Kurrent Inc.
 Although not all aspects of the KurrentDB gRPC API are implemented, most
 features are presented in an easy-to-use interface.
 
-These clients have been tested to work with KurrentDB version 25.1 and 25.0, EventStoreDB
-versions 24.10 and EventStoreDB 23.10, both with and without SSL/TLS, in both single-server and
-cluster modes, across Python versions 3.10, 3.11, 3.12, 3.13, and 3.14.
+These clients have been tested to work with KurrentDB versions 25.0, 25.1, 26.0,
+and 26.1, and EventStoreDB versions 23.10 and 24.10, with and without SSL/TLS,
+in both single-server and cluster modes, across Python versions 3.10, 3.11, 3.12,
+3.13, and 3.14.
 
 The test suite has 100% line and branch coverage. The code has typing annotations
 checked strictly with mypy. The code is formatted with black and isort, and checked
@@ -1715,10 +1716,10 @@ so far, in the order they were recorded. We can see the three events of `stream_
 
 ```python
 # Read all events (creates a streaming gRPC call).
-read_response = client.read_all()
+with client.read_all() as read_response:
+    # Convert the iterator into a sequence of recorded events.
+    events = tuple(read_response)
 
-# Convert the iterator into a sequence of recorded events.
-events = tuple(read_response)
 assert len(events) > 3  # more than three
 
 # Convert the sequence of recorded events into a set of event IDs.
@@ -1737,17 +1738,14 @@ receive, `event2` is the second, and `event3` is the third.
 
 ```python
 # Read all events forwards from a commit position.
-read_response = client.read_all(
+with client.read_all(
     commit_position=commit_position1
-)
-
-# Step through the "read response" iterator.
-assert next(read_response) == event1
-assert next(read_response) == event2
-assert next(read_response) == event3
+) as read_response:
 
-# Stop the iterator.
-read_response.stop()
+    # Step through the "read response" iterator.
+    assert next(read_response) == event1
+    assert next(read_response) == event2
+    assert next(read_response) == event3
 ```
 
 The example below shows how to read all events recorded in the database in reverse
@@ -1757,31 +1755,27 @@ and the snapshot.
 
 ```python
 # Read all events backwards from the end.
-read_response = client.read_all(
+with client.read_all(
     backwards=True
-)
+) as read_response:
 
-# Step through the "read response" iterator.
-assert next(read_response).type == "DogLearnedTrick"
-assert next(read_response).type == "Snapshot"
-assert next(read_response).type == "DogLearnedTrick"
-assert next(read_response).type == "DogLearnedTrick"
-assert next(read_response).type == "DogRegistered"
-
-# Stop the iterator.
-read_response.stop()
+    # Step through the "read response" iterator.
+    assert next(read_response).type == "DogLearnedTrick"
+    assert next(read_response).type == "Snapshot"
+    assert next(read_response).type == "DogLearnedTrick"
+    assert next(read_response).type == "DogLearnedTrick"
+    assert next(read_response).type == "DogRegistered"
 ```
 
 The example below shows how to read a limited number of events
 forwards from a specific commit position.
 
 ```python
-events = tuple(
-    client.read_all(
-        commit_position=commit_position1,
-        limit=1,
-    )
-)
+with client.read_all(
+    commit_position=commit_position1,
+    limit=1,
+) as read_response:
+    events = tuple(read_response)
 
 assert len(events) == 1
 assert events[0] == event1
@@ -1792,12 +1786,11 @@ in the database backwards from the end. In this case, the limit is 1, and
 so we receive the last recorded event.
 
 ```python
-events = tuple(
-    client.read_all(
-        backwards=True,
-        limit=1,
-    )
-)
+with client.read_all(
+    backwards=True,
+    limit=1,
+) as read_response:
+    events = tuple(read_response)
 
 assert len(events) == 1
 
@@ -2096,16 +2089,17 @@ from the first recorded event in the database.
 
 ```python
 # Subscribe from the first recorded event in the database.
-catchup_subscription = client.subscribe_to_all()
+with client.subscribe_to_all() as catchup_subscription:
+    ...
 ```
 
-The example below shows that catch-up subscriptions do not stop
-automatically, but block when the last recorded event is received,
-and then continue when subsequent events are recorded.
+The example below shows that catch-up subscriptions block when the
+last recorded event is received, and then continue when subsequent
+events are recorded.
 
 ```python
-from time import sleep
-from threading import Thread
+import time
+import threading
 
 
 # Append a new event to a new stream.
@@ -2119,30 +2113,53 @@ client.append_to_stream(
 )
 
 
-# Receive events from the catch-up subscription in a different thread.
-received_events = []
-
-def receive_events():
-    for event in catchup_subscription:
-        received_events.append(event)
+# Receive events from a catch-up subscription in a different thread.
+class SubscribeToAll(threading.Thread):
+    def __init__(self, client, **subscription_kwargs):
+        super().__init__()
+        self._client = client
+        self._is_running = threading.Event()
+        self._subscription_kwargs = subscription_kwargs
+        self._subscription = None
+        self._seen_event_ids = set()
+        self._last_commit_position = None
+        self.start()
 
+    def run(self):
+        with self._client.subscribe_to_all(
+            **self._subscription_kwargs
+        ) as subscription:
+            self._subscription = subscription
+            self._is_running.set()
+            for event in subscription:
+                self._seen_event_ids.add(event.id)
+                self._last_commit_position = event.commit_position
 
-def wait_for_event(event):
-    for _ in range(100):
-        for received in reversed(received_events):
-            if event == received:
+    def stop(self):
+        if not self._is_running.wait(timeout=5):
+            raise TimeoutError("Subscription thread didn't start")
+        self._subscription.stop()
+        self.join()
+        self._subscription = None
+
+    def wait_for_event(self, event):
+        for _ in range(100):
+            if event.id in self._seen_event_ids:
                 return
+            else:
+                time.sleep(0.1)
         else:
-            sleep(0.1)
-    else:
-        raise AssertionError("Event wasn't received")
+            raise AssertionError("Event wasn't received")
+
+    @property
+    def last_commit_position(self):
+        return self._last_commit_position
 
 
-thread = Thread(target=receive_events, daemon=True)
-thread.start()
+subscription_to_all = SubscribeToAll(client=client)
 
 # Wait to receive event4.
-wait_for_event(event4)
+subscription_to_all.wait_for_event(event4)
 
 # Append another event whilst the subscription is running.
 event5 = NewEvent(type='OrderUpdated', data=b'{}')
@@ -2152,17 +2169,16 @@ client.append_to_stream(
     events=[event5],
 )
 
-# Wait for the subscription to block.
-wait_for_event(event5)
+# Wait to receive event5.
+subscription_to_all.wait_for_event(event5)
 
-# Stop the subscription.
-catchup_subscription.stop()
-thread.join()
+# Stop the subscription thread.
+subscription_to_all.stop()
 ```
 
 The example below shows how to subscribe to events recorded after a
 particular commit position, in this case from the commit position of
-the last recorded event that was received above. Then, another event is
+the last recorded event that was received above. Another event is
 recorded before the subscription is restarted. And three more events are
 recorded whilst the subscription is running. These four events are
 received in the order they were recorded.
@@ -2180,15 +2196,13 @@ client.append_to_stream(
 
 # Restart subscribing to all events after the
 # commit position of the last received event.
-catchup_subscription = client.subscribe_to_all(
-    commit_position=received_events[-1].commit_position
+subscription_to_all = SubscribeToAll(
+    client=client,
+    commit_position=subscription_to_all.last_commit_position
 )
 
-thread = Thread(target=receive_events, daemon=True)
-thread.start()
-
 # Wait for event6.
-wait_for_event(event6)
+subscription_to_all.wait_for_event(event6)
 
 # Append three more events to a new stream.
 stream_name3 = str(uuid.uuid4())
@@ -2203,13 +2217,12 @@ client.append_to_stream(
 )
 
 # Wait for events 7, 8 and 9.
-wait_for_event(event7)
-wait_for_event(event8)
-wait_for_event(event9)
+subscription_to_all.wait_for_event(event7)
+subscription_to_all.wait_for_event(event8)
+subscription_to_all.wait_for_event(event9)
 
-# Stop the subscription.
-catchup_subscription.stop()
-thread.join()
+# Stop the subscription thread.
+subscription_to_all.stop()
 ```
 
 The catch-up subscription call is ended as soon as the subscription object's
@@ -2263,7 +2276,10 @@ the first recorded event in a stream.
 
 ```python
 # Subscribe from the start of 'stream2'.
-subscription = client.subscribe_to_stream(stream_name=stream_name2)
+with client.subscribe_to_stream(
+    stream_name=stream_name2
+) as subscription:
+    ...
 ```
 
 The example below shows how to start a catch-up subscription from
@@ -2271,10 +2287,11 @@ a particular stream position.
 
 ```python
 # Subscribe to stream2, from the second recorded event.
-subscription = client.subscribe_to_stream(
+with client.subscribe_to_stream(
     stream_name=stream_name2,
     stream_position=1,
-)
+) as subscription:
+    ...
 ```
 
 ### Subscribe using secondary index<a id="subscribe-to-index"></a>
@@ -2528,7 +2545,10 @@ giving `RecordedEvent` objects. It also has `ack()`, `nack()` and `stop()`
 methods.
 
 ```python
-subscription = client.read_subscription_to_all(group_name=group_name1)
+with client.read_subscription_to_all(
+    group_name=group_name1
+) as subscription:
+    ...
 ```
 
 The `ack()` method should be used by a consumer to "acknowledge" to the server that
@@ -2550,15 +2570,18 @@ examples below.
 ```python
 received_events = []
 
-for event in subscription:
-    received_events.append(event)
+with client.read_subscription_to_all(
+    group_name=group_name1
+) as subscription:
+    for event in subscription:
+        received_events.append(event)
 
-    # Acknowledge the received event.
-    subscription.ack(event)
+        # Acknowledge the received event.
+        subscription.ack(event)
 
-    # Stop when 'event9' has been received.
-    if event == event9:
-        subscription.stop()
+        # Stop when 'event9' has been received.
+        if event == event9:
+            subscription.stop()
 ```
 
 The `nack()` should be used by a consumer to "negatively acknowledge" to the server that
@@ -2610,9 +2633,6 @@ class ExampleConsumer:
                     self.subscription.ack(event)
                     self.after_ack(event)
 
-    def stop(self):
-        self.subscription.stop()
-
     def policy(self, event):
         # Raise an exception when we see "event5".
         if event == event5:
@@ -2630,17 +2650,17 @@ class ExampleConsumer:
             # Stop the consumer, so we can continue with the examples.
             self.stop()
 
+    def stop(self):
+        self.subscription.stop()
+
 
 # Create subscription.
 group_name = f"group-{uuid.uuid4()}"
 client.create_subscription_to_all(group_name, commit_position=commit_position1)
 
-# Read subscription.
-subscription = client.read_subscription_to_all(group_name)
-
 # Construct consumer.
 consumer = ExampleConsumer(
-    subscription=subscription,
+    subscription=client.read_subscription_to_all(group_name),
     max_retry_count=5,
     final_action="park",
 )
@@ -2819,28 +2839,25 @@ This method returns a `PersistentSubscription` object, which is an iterator
 giving `RecordedEvent` objects, that also has `ack()`, `nack()` and `stop()`
 methods.
 
-```python
-subscription = client.read_subscription_to_stream(
-    group_name=group_name2,
-    stream_name=stream_name2,
-)
-```
-
 The example below iterates over the subscription object, and calls `ack()`.
 The subscription's `stop()` method is called when we have received `event6`,
 stopping the iteration, so that we can continue with the examples below.
 
 ```python
 events = []
-for event in subscription:
-    events.append(event)
+with client.read_subscription_to_stream(
+    group_name=group_name2,
+    stream_name=stream_name2,
+) as subscription:
+    for event in subscription:
+        events.append(event)
 
-    # Acknowledge the received event.
-    subscription.ack(event)
+        # Acknowledge the received event.
+        subscription.ack(event)
 
-    # Stop when 'event6' has been received.
-    if event == event6:
-        subscription.stop()
+        # Stop when 'event6' has been received.
+        if event == event6:
+            break
 ```
 
 We can check we received all the events that were appended to `stream_name2`
@@ -3192,7 +3209,7 @@ to process all the recorded events, the projection "state" is obtained.
 We can see that the projection has processed three events.
 
 ```python
-sleep(1)  # allow time for projection to process recorded events
+time.sleep(1)  # allow time for projection to process recorded events
 
 projection_state = client.get_projection_state(projection_name)