kurrentdbclient 0.4__tar.gz → 1.0__tar.gz

{kurrentdbclient-0.4 → kurrentdbclient-1.0}/LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2022, John Bywater
+Copyright (c) 2025, John Bywater
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

kurrentdbclient-0.4/README.md → kurrentdbclient-1.0/PKG-INFO

@@ -1,3 +1,42 @@
+Metadata-Version: 2.3
+Name: kurrentdbclient
+Version: 1.0
+Summary: Python gRPC Client for KurrentDB
+License: BSD 3-Clause
+Author: John Bywater
+Author-email: john.bywater@appropriatesoftware.net
+Requires-Python: >=3.9,<4.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: BSD License
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: opentelemetry
+Requires-Dist: grpcio[protobuf] (>=1.71.0,<1.72)
+Requires-Dist: opentelemetry-api (>=1.28.0,<2.0.0) ; extra == "opentelemetry"
+Requires-Dist: opentelemetry-instrumentation (>=0.49b0,<0.50) ; extra == "opentelemetry"
+Requires-Dist: opentelemetry-semantic-conventions (>=0.49b0,<0.50) ; extra == "opentelemetry"
+Requires-Dist: typing_extensions
+Project-URL: Homepage, https://github.com/pyeventsourcing/kurrentdbclient
+Project-URL: Repository, https://github.com/pyeventsourcing/kurrentdbclient
+Description-Content-Type: text/markdown
+
+<a href="https://kurrent.io">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://github.com/pyeventsourcing/kurrentdbclient/raw/1.0/KurrentLogo-White.png.png">
+    <source media="(prefers-color-scheme: light)" srcset="https://github.com/pyeventsourcing/kurrentdbclient/raw/1.0/KurrentLogo-Black.png">
+    <img alt="Kurrent" src="https://github.com/pyeventsourcing/kurrentdbclient/raw/1.0/KurrentLogo-Plum.png" height="50%" width="50%">
+  </picture>
+</a>
+
+Please note: following the rebranding of EventStoreDB to KurrentDB, this package
+is a rebranding of the [`esdbclient`](https://pypi.org/project/esdbclient) package.
+
 # Python gRPC Client for KurrentDB
 
 This [Python package](https://pypi.org/project/kurrentdbclient/) provides multithreaded and asyncio Python
@@ -7,18 +46,18 @@ The multithreaded `KurrentDBClient` is described in detail below. Please scroll
 down for <a href="#asyncio-client">information</a> about `AsyncKurrentDBClient`.
 
 These clients have been developed and are being maintained in a collaboration
-with the KurrentDB team, and are officially support by Kurrent Inc.
+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 LTS versions 22.10, 23.10,
-and 24.10, without and without SSL/TLS, with both single-server
-and cluster modes, and with Python versions 3.8, 3.9, 3.10, 3.11, 3.12, and 3.13.
+These clients have been tested to work with KurrentDB 25.0.0, without and without
+SSL/TLS, with both single-server and cluster modes, and with Python versions
+3.9, 3.10, 3.11, 3.12, and 3.13.
 
 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
 with flake8. Poetry is used for package management during development, and for
-building and publishing distributions to [PyPI](https://pypi.org/project/esdbclient/).
+building and publishing distributions to [PyPI](https://pypi.org/project/kurrentdbclient/).
 
 For an example of usage, see the [eventsourcing-eventstoredb](
 https://github.com/pyeventsourcing/eventsourcing-eventstoredb) package.
@@ -75,10 +114,13 @@ https://github.com/pyeventsourcing/eventsourcing-eventstoredb) package.
 * [Projections](#projections)
   * [Create projection](#create-projection)
   * [Get projection state](#get-projection-state)
-  * [Get projection statistics](#get-projection-statistics)
   * [Update projection](#update-projection)
-  * [Enable projection](#enable-projection)
+  * [Get projection statistics](#get-projection-statistics)
+  * [List all projection statistics](#list-all-projection-statistics)
+  * [List continuous projection statistics](#list-continuous-projection-statistics)
   * [Disable projection](#disable-projection)
+  * [Enable projection](#enable-projection)
+  * [Abort projection](#abort-projection)
   * [Reset projection](#reset-projection)
   * [Delete projection](#delete-projection)
   * [Restart projections subsystem](#restart-projections-subsystem)
@@ -130,7 +172,7 @@ import uuid
 
 from kurrentdbclient import KurrentDBClient, NewEvent, StreamState
 
-# Construct KurrentDBClient with an KurrentDB URI. The
+# Construct KurrentDBClient with a KurrentDB URI. The
 # connection string URI specifies that the client should
 # connect to an "insecure" server running on port 2113.
 
@@ -176,7 +218,7 @@ commit_position1 = client.append_to_stream(
 # Append events to an existing stream. The "current version"
 # is the "stream position" of the last recorded event in a
 # stream. We have recorded two new events, so the "current
-# version" is 1. The exception 'WrongCurrentVersion' will be
+# version" is 1. The exception 'WrongCurrentVersionError' will be
 # raised if an incorrect value is given.
 
 commit_position2 = client.append_to_stream(
@@ -287,9 +329,9 @@ The KurrentDB server can be run locally using the official Docker container imag
 
 For development, you can run a "secure" KurrentDB server using the following command.
 
-    $ docker run -d --name kurrentdb-secure -it -p 2113:2113 --env "HOME=/tmp" docker.eventstore.com/eventstore/eventstoredb-ee:24.10.0-x64-8.0-bookworm-slim --dev
+    $ docker run -d --name kurrentdb-secure -it -p 2113:2113 --env "HOME=/tmp" docker.eventstore.com/kurrent-latest/kurrentdb:25.0.0-x64-8.0-bookworm-slim --dev
 
-As we will see, your client will need an KurrentDB connection string URI as the value
+As we will see, your client will need a KurrentDB connection string URI as the value
 of its `uri` constructor argument. The connection string for this "secure" KurrentDB
 server would be:
 
@@ -317,7 +359,7 @@ server_certificate = ssl.get_server_certificate(addr=('localhost', 2113))
 
 Alternatively, you can start an "insecure" server using the following command.
 
-    $ docker run -d --name kurrentdb-insecure -it -p 2113:2113 docker.eventstore.com/eventstore/eventstoredb-ee:24.10.0-x64-8.0-bookworm-slim --insecure
+    $ docker run -d --name kurrentdb-insecure -it -p 2113:2113 docker.eventstore.com/kurrent-latest/kurrentdb:25.0.0-x64-8.0-bookworm-slim --insecure
 
 The connection string URI for this "insecure" server would be:
 
@@ -361,7 +403,7 @@ from kurrentdbclient import KurrentDBClient
 The `KurrentDBClient` class has one required constructor argument, `uri`, and three
 optional constructor argument, `root_certificates`, `private_key`, and `certificate_chain`.
 
-The `uri` argument is expected to be an KurrentDB connection string URI that
+The `uri` argument is expected to be a KurrentDB connection string URI that
 conforms with the standard KurrentDB "kdb" or "kdb+discover" URI schemes.
 
 The client must be configured to create a "secure" connection to a "secure" server,
@@ -412,7 +454,7 @@ client = KurrentDBClient(
 
 ## Connection strings<a id="connection-strings"></a>
 
-An KurrentDB connection string is a URI that conforms with one of two possible
+A KurrentDB connection string is a URI that conforms with one of two possible
 schemes: either the "kdb" scheme, or the "kdb+discover" scheme.
 
 The syntax and semantics of the KurrentDB URI schemes are described below. The
@@ -432,7 +474,7 @@ In the "kdb" URI scheme, after the optional user info string, there must be at l
 one gRPC target. If there are several gRPC targets, they must be separated from each
 other with the "," character.
 
-Each gRPC target should indicate an KurrentDB gRPC server socket, all in the same
+Each gRPC target should indicate a KurrentDB gRPC server socket, all in the same
 KurrentDB cluster, by specifying a host and a port number separated with the ":"
 character. The host may be a hostname that can be resolved to an IP address, or an IP
 address.
@@ -548,13 +590,13 @@ Here are some examples of KurrentDB connection string URIs.
 The following URI will cause the client to make an "insecure" connection to
 gRPC target `'localhost:2113'`. Because the client's node preference is "follower",
 methods that can be called on a follower should complete successfully, methods that
-require a leader will raise a `NodeIsNotLeader` exception.
+require a leader will raise a `NodeIsNotLeaderError` exception.
 
     kdb://127.0.0.1:2113?Tls=false&NodePreference=follower
 
 The following URI will cause the client to make an "insecure" connection to
 gRPC target `'localhost:2113'`. Because the client's node preference is "leader",
-if this node is not a leader, then a `NodeIsNotLeader` exception will be raised by
+if this node is not a leader, then a `NodeIsNotLeaderError` exception will be raised by
 all methods.
 
     kdb://127.0.0.1:2113?Tls=false&NodePreference=leader
@@ -563,7 +605,7 @@ The following URI will cause the client to make a "secure" connection to
 gRPC target `'localhost:2113'` with username `'admin'` and password `'changeit'`
 as the default call credentials when making calls to the KurrentDB gRPC API.
 Because the client's node preference is "leader", by default, if this node is not
-a leader, then a `NodeIsNotLeader` exception will be raised by all methods.
+a leader, then a `NodeIsNotLeaderError` exception will be raised by all methods.
 
     kdb://admin:changeit@localhost:2113
 
@@ -611,7 +653,7 @@ This package defines a `NewEvent` class and a `RecordedEvent` class. The
 
 ### New events<a id="new-events"></a>
 
-The `NewEvent` class should be used when writing events to an KurrentDB database.
+The `NewEvent` class should be used when writing events to a KurrentDB database.
 You will need to construct new event objects before calling `append_to_stream()`.
 
 The `NewEvent` class is a frozen Python dataclass. It has two required constructor
@@ -665,7 +707,7 @@ assert new_event2.id == event_id
 
 ### Recorded events<a id="recorded-events"></a>
 
-The `RecordedEvent` class is used when reading events from an KurrentDB
+The `RecordedEvent` class is used when reading events from a KurrentDB
 database. The client will return event objects of this type from all methods
 that return recorded events, such as `get_stream()`, `subscribe_to_all()`,
 and `read_subscription_to_all()`. You do not need to construct recorded event objects.
@@ -837,7 +879,7 @@ that indicates the stream position of the last recorded event in the stream, or
 `StreamState.NO_STREAM` if the stream does not yet exist or has been deleted. The
 stream positions are zero-based and gapless, so that if a stream has two events, the
 `current_version` should be 1. If an incorrect value is given, this method will raise a
-`WrongCurrentVersion` exception. This behavior is designed to provide concurrency
+`WrongCurrentVersionError` exception. This behavior is designed to provide concurrency
 control when recording new events. The correct value of `current_version` for any stream
 can be obtained by calling `get_current_version()`. However, the typical approach is to
 reconstruct an aggregate from the recorded events, so that the version of the aggregate
@@ -846,7 +888,7 @@ events, and then use the current version of the aggregate as the value of the
 `current_version` argument when appending the new aggregate events. This ensures
 the consistency of the recorded aggregate events, because operations that generate
 new aggregate events can be retried with a freshly reconstructed aggregate if
-a `WrongCurrentVersion` exception is encountered when recording new events. This
+a `WrongCurrentVersionError` exception is encountered when recording new events. This
 controlling behavior can be entirely disabled by setting the value of the `current_version`
 argument to the constant `StreamState.ANY`. More selectively, this behaviour can be
 disabled for existing streams by setting the value of the `current_version`
@@ -933,7 +975,7 @@ If the method call initially failed and the new events were not in fact recorded
 makes good sense, when the method call is retried, that the new events are recorded
 and that the method call returns successfully. If the concurrency controls have not been disabled,
 that is if the `current version` is either `StreamState.NO_STREAM` or an integer value, and
-if a `WrongCurrentVersion` exception is raised when retrying the method call, then we can assume
+if a `WrongCurrentVersionError` exception is raised when retrying the method call, then we can assume
 both that the initial method call did not in fact successfully record the events, and also
 that subsequent events have in the meantime been recorded by somebody else. In this case,
 an application command which generated the new events may need to be executed again. And
@@ -947,7 +989,7 @@ can be sure the events have been recorded.
 
 The example below shows the `append_to_stream()` method being called again with events
 `event2` and `event3`, and with `current_version=0`. We can see that repeating the call
-to `append_to_stream()` returns successfully without raising a `WrongCurrentVersion`
+to `append_to_stream()` returns successfully without raising a `WrongCurrentVersionError`
 exception, as it would if the `append_to_stream()` operation were not idempotent.
 
 ```python
@@ -1115,15 +1157,15 @@ assert events[0] == event1
 assert events[1] == event2
 ```
 
-The `read_stream()` and `get_stream()` methods will raise a `NotFound` exception if the
+The `read_stream()` and `get_stream()` methods will raise a `NotFoundError` exception if the
 named stream has never existed or has been deleted.
 
 ```python
-from kurrentdbclient.exceptions import NotFound
+from kurrentdbclient.exceptions import NotFoundError
 
 try:
     client.get_stream('does-not-exist')
-except NotFound:
+except NotFoundError:
     pass  # The stream does not exist.
 else:
     raise Exception("Shouldn't get here")
@@ -1138,7 +1180,7 @@ when iterating over the "read response" starts, which means that the method retu
 before the streaming starts, and so there is no chance for any decorators to catch
 any connection issues.
 
-For the same reason, `read_stream()` will not raise a `NotFound` exception when
+For the same reason, `read_stream()` will not raise a `NotFoundError` exception when
 the stream does not exist, until iterating over the "read response" object begins.
 
 If you are reading a very large stream, then you might prefer to call `read_stream()`,
@@ -1203,10 +1245,10 @@ Event-sourced aggregates are typically reconstructed from recorded events by cal
 a mutator function for each recorded event, evolving from an initial state
 `None` to the current state of the aggregate. The function `get_aggregate()` shows
 how this can be done. The aggregate ID is used as a stream name. The exception
-`AggregateNotFound` is raised if the aggregate stream is not found.
+`AggregateNotFoundError` is raised if the aggregate stream is not found.
 
 ```python
-class AggregateNotFound(Exception):
+class AggregateNotFoundError(Exception):
     """Raised when an aggregate is not found."""
 
 
@@ -1219,8 +1261,8 @@ def get_aggregate(aggregate_id, mutator_func):
             stream_name=stream_name,
             stream_position=None
         )
-    except NotFound as e:
-        raise AggregateNotFound(aggregate_id) from e
+    except NotFoundError as e:
+        raise AggregateNotFoundError(aggregate_id) from e
     else:
         # Reconstruct aggregate from recorded events.
         aggregate = None
@@ -1279,7 +1321,7 @@ def get_aggregate(aggregate_id, mutator_func):
             backwards=True,
             limit=1
         )
-    except NotFound:
+    except NotFoundError:
         stream_position = None
     else:
         assert len(snapshots) == 1
@@ -1293,8 +1335,8 @@ def get_aggregate(aggregate_id, mutator_func):
             stream_name=stream_name,
             stream_position=stream_position
         )
-    except NotFound as e:
-        raise AggregateNotFound(aggregate_id) from e
+    except NotFoundError as e:
+        raise AggregateNotFoundError(aggregate_id) from e
     else:
         recorded_events += events
 
@@ -2267,7 +2309,7 @@ duration in seconds between recording "acknowledgements" (acks). The default val
 
 The optional `max_subscriber_count` argument is a Python `int` which sets the maximum
 number of concurrent readers of the persistent subscription, beyond which attempts to
-read the persistent subscription will raise a `MaximumSubscriptionsReached` error.
+read the persistent subscription will raise a `MaximumSubscriptionsReachedError` exception.
 
 The optional `live_buffer_size` argument is a Python `int` which sets the size of the
 buffer (in-memory) holding newly recorded events. The default value of `live_buffer_size`
@@ -2559,7 +2601,7 @@ duration in seconds between recording "acknowledgements" (acks). The default val
 
 The optional `max_subscriber_count` argument is a Python `int` which sets the maximum
 number of concurrent readers of the persistent subscription, beyond which attempts to
-read the persistent subscription will raise a `MaximumSubscriptionsReached` error.
+read the persistent subscription will raise a `MaximumSubscriptionsReachedError` exception.
 
 The optional `live_buffer_size` argument is a Python `int` which sets the size of the
 buffer (in-memory) holding newly recorded events. The default value of `live_buffer_size`
@@ -2992,6 +3034,41 @@ projection_state = client.get_projection_state(name=projection_name)
 assert projection_state.value == {'count': 3}
 ```
 
+### Update projection<a id="update-projection"></a>
+
+*requires leader*
+
+The `update_projection()` method can be used to update a projection.
+
+This method has two required arguments, `name` and `query`.
+
+The required `name` argument is a Python `str` which specifies the name of the projection
+to be updated.
+
+The required `query` argument is a Python `str` which defines what the projection will do.
+
+This method also has three optional arguments, `emit_enabled`, `timeout`, and `credentials`.
+
+The optional `emit_enabled` argument is a Python `bool` which specifies whether a
+projection will be able to emit events. If a `True` value is specified, the projection
+will be able to emit events. If a `False` value is specified, the projection will not
+be able to emit events. The default value of `emit_enabled` is `False`.
+
+Please note, `emit_enabled` must be `True` if your projection query includes a call
+to `emit()`, otherwise the projection will not run.
+
+Please note, it is not possible to update `track_emitted_streams` via the gRPC API.
+
+The optional `timeout` argument is a Python `float` which sets a
+maximum duration, in seconds, for the completion of the gRPC operation.
+
+The optional `credentials` argument can be used to
+override call credentials derived from the connection string URI.
+
+```python
+client.update_projection(name=projection_name, query=projection_query)
+```
+
 ### Get projection statistics<a id="get-projection-statistics"></a>
 
 *requires leader*
@@ -3019,30 +3096,35 @@ statistics = client.get_projection_statistics(name=projection_name)
 A `ProjectionStatistics` object is returned. The attributes of this object
 have values that represent the progress of the projection.
 
-### Update projection<a id="update-projection"></a>
+
+### List all projection statistics<a id="list-all-projection-statistics"></a>
 
 *requires leader*
 
-The `update_projection()` method can be used to update a projection.
+The `list_all_projection_statistics()` method can be used to get a list of projection statistics for all projections.
 
-This method has two required arguments, `name` and `query`.
+This method has two optional arguments, `timeout` and `credentials`.
 
-The required `name` argument is a Python `str` which specifies the name of the projection
-to be updated.
+The optional `timeout` argument is a Python `float` which sets a
+maximum duration, in seconds, for the completion of the gRPC operation.
 
-The required `query` argument is a Python `str` which defines what the projection will do.
+The optional `credentials` argument can be used to
+override call credentials derived from the connection string URI.
 
-This method also has three optional arguments, `emit_enabled`, `timeout`, and `credentials`.
+This method returns a list of `ProjectionStatistics` objects that each represent
+a projection.
 
-The optional `emit_enabled` argument is a Python `bool` which specifies whether a
-projection will be able to emit events. If a `True` value is specified, the projection
-will be able to emit events. If a `False` value is specified, the projection will not
-be able to emit events. The default value of `emit_enabled` is `False`.
+```python
+statistics = client.list_all_projection_statistics()
+```
 
-Please note, `emit_enabled` must be `True` if your projection query includes a call
-to `emit()`, otherwise the projection will not run.
+### List continuous projection statistics<a id="list-continuous-projection-statistics"></a>
 
-Please note, it is not possible to update `track_emitted_streams` via the gRPC API.
+*requires leader*
+
+The `list_continuous_projection_statistics()` method can be used to get a list of projection statistics for all continuous projections.
+
+This method has two optional arguments, `timeout` and `credentials`.
 
 The optional `timeout` argument is a Python `float` which sets a
 maximum duration, in seconds, for the completion of the gRPC operation.
@@ -3050,8 +3132,33 @@ maximum duration, in seconds, for the completion of the gRPC operation.
 The optional `credentials` argument can be used to
 override call credentials derived from the connection string URI.
 
+This method returns a list of `ProjectionStatistics` objects that each represent
+a projection.
+
 ```python
-client.update_projection(name=projection_name, query=projection_query)
+statistics = client.list_continuous_projection_statistics()
+```
+
+### Disable projection<a id="disable-projection"></a>
+
+*requires leader*
+
+The `disable_projection()` method can be used to disable (stop running) a projection.
+When a projection is stopped using this method, a checkpoint will be written.
+
+This method has a required `name` argument, which is a Python `str` that
+specifies the name of the projection to be disabled.
+
+This method also has two optional arguments, `timeout`, and `credentials`.
+
+The optional `timeout` argument is a Python `float` which sets a
+maximum duration, in seconds, for the completion of the gRPC operation.
+
+The optional `credentials` argument can be used to
+override call credentials derived from the connection string URI.
+
+```python
+client.disable_projection(name=projection_name)
 ```
 
 ### Enable projection<a id="enable-projection"></a>
@@ -3076,11 +3183,13 @@ override call credentials derived from the connection string URI.
 client.enable_projection(name=projection_name)
 ```
 
-### Disable projection<a id="disable-projection"></a>
+### Abort projection<a id="abort-projection"></a>
 
 *requires leader*
 
-The `disable_projection()` method can be used to disable (stop running) a projection.
+The `abort_projection()` method can be used to abort (stop running) a projection.
+When a projection is stopped using this method, it will be stopped without writing
+a checkpoint.
 
 This method has a required `name` argument, which is a Python `str` that
 specifies the name of the projection to be disabled.
@@ -3094,7 +3203,7 @@ The optional `credentials` argument can be used to
 override call credentials derived from the connection string URI.
 
 ```python
-client.disable_projection(name=projection_name)
+client.abort_projection(name=projection_name)
 ```
 
 ### Reset projection<a id="reset-projection"></a>
@@ -3159,6 +3268,7 @@ client.delete_projection(name=projection_name)
 
 Please note, a projection must be disabled before it can be deleted.
 
+
 ### Restart projections subsystem<a id="restart-projections-subsystem"></a>
 
 *requires leader*
@@ -3223,14 +3333,14 @@ and then they will all return normally.
 client.reconnect()
 ```
 
+Reconnection will happen automatically in many cases, due to the `@autoreconnect`
+decorator.
+
 An example of when it might be desirable to reconnect manually is when (for performance
 reasons) the client's node preference is to be connected to a follower node in the
 cluster, and, after a cluster leader election, the follower becomes the leader.
-Reconnecting to a follower node in this case is currently beyond the capabilities of
-this client, but this behavior might be implemented in a future release.
-
-Reconnection will happen automatically in many cases, due to the `@autoreconnect`
-decorator.
+Automatic reconnection to a follower node in this case is currently beyond the
+capabilities of this client, but this behavior might be implemented in a future release.
 
 ### Close<a id="close"></a>
 
@@ -3611,7 +3721,7 @@ span.
 
 ## Communities<a id="communities"></a>
 
-- [Issues](https://github.com/pyeventsourcing/esdbclient/issues)
+- [Issues](https://github.com/pyeventsourcing/kurrentdbclient/issues)
 - [Discuss](https://discuss.eventstore.com/)
 - [Discord (Event Store)](https://discord.gg/Phn9pmCw3t)
 
@@ -3736,3 +3846,4 @@ Update the `poetry.lock` file, and the project's virtual environment, using the
 following command.
 
     $ make update-packages
+