kurrentdbclient 1.2.3__tar.gz → 1.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kurrentdbclient
-Version: 1.2.3
+Version: 1.3.0
 Summary: Python gRPC Client for KurrentDB
 License: BSD-3-Clause
 License-File: LICENSE
@@ -19,7 +19,7 @@ Classifier: Programming Language :: Python
 Provides-Extra: opentelemetry
 Requires-Dist: googleapis-common-protos
 Requires-Dist: grpcio-status
-Requires-Dist: grpcio[protobuf] (>=1.75.1,<2.0)
+Requires-Dist: grpcio[protobuf] (>=1.80.0,<2.0)
 Requires-Dist: opentelemetry-api (>=1.28.0,<2.0) ; extra == "opentelemetry"
 Requires-Dist: opentelemetry-instrumentation (>=0.62b1) ; extra == "opentelemetry"
 Requires-Dist: opentelemetry-semantic-conventions (>=0.62b1) ; extra == "opentelemetry"
@@ -83,7 +83,7 @@ https://github.com/pyeventsourcing/eventsourcing-kurrentdb) package.
   * [Query string](#query-string)
   * [Examples](#examples)
 * [Event objects](#event-objects)
-  * [New events](#new-events)
+  * [New events](#the-newevent-class)
   * [Recorded events](#recorded-events)
 * [Streams](#streams)
   * [Append events](#append-events)

{kurrentdbclient-1.2.3 → kurrentdbclient-1.3.0}/README.md

@@ -53,7 +53,7 @@ https://github.com/pyeventsourcing/eventsourcing-kurrentdb) package.
   * [Query string](#query-string)
   * [Examples](#examples)
 * [Event objects](#event-objects)
-  * [New events](#new-events)
+  * [New events](#the-newevent-class)
   * [Recorded events](#recorded-events)
 * [Streams](#streams)
   * [Append events](#append-events)

{kurrentdbclient-1.2.3 → kurrentdbclient-1.3.0}/kurrentdbclient/__init__.py

@@ -12,8 +12,10 @@ from kurrentdbclient.events import (
     FellBehind,
     NewEvent,
     NewEvents,
+    NewRecord,
     RecordedEvent,
     StreamState,
+    StreamStateCheck,
 )
 from kurrentdbclient.persistent import (
     AsyncPersistentSubscription,
@@ -26,7 +28,7 @@ from kurrentdbclient.streams import (
     ReadResponse,
 )
 
-__version__ = "1.2.3"
+__version__ = "1.3.0"
 
 __all__ = [
     "DEFAULT_EXCLUDE_FILTER",
@@ -44,8 +46,10 @@ __all__ = [
     "KurrentDBClient",
     "NewEvent",
     "NewEvents",
+    "NewRecord",
     "RecordedEvent",
     "ReadResponse",
     "StreamState",
+    "StreamStateCheck",
     "PersistentSubscription",
 ]

{kurrentdbclient-1.2.3 → kurrentdbclient-1.3.0}/kurrentdbclient/asyncio_client.py

@@ -45,7 +45,14 @@ from kurrentdbclient.connection_spec import (
     URI_SCHEMES_NON_DISCOVER,
     grpc_target,
 )
-from kurrentdbclient.events import NewEvent, NewEvents, RecordedEvent, StreamState
+from kurrentdbclient.events import (
+    NewEvent,
+    NewEvents,
+    NewRecord,
+    RecordedEvent,
+    StreamState,
+    StreamStateCheck,
+)
 from kurrentdbclient.exceptions import (
     DeadlineExceededError,
     DiscoveryFailedError,
@@ -62,6 +69,7 @@ if TYPE_CHECKING:
     from kurrentdbclient.persistent import ConsumerStrategy, SubscriptionInfo
     from kurrentdbclient.projections import ProjectionState, ProjectionStatistics
     from kurrentdbclient.streams import AsyncReadResponse
+    from kurrentdbclient.v2streams import AppendRecordsResult
 
 _TCallable = TypeVar("_TCallable", bound=Callable[..., Any])
 
@@ -331,6 +339,33 @@ class AsyncKurrentDBClient(BaseKurrentDBClient):
             credentials=credentials or self._call_credentials,
         )
 
+    @retrygrpc
+    @autoreconnect
+    async def append_records(
+        self,
+        /,
+        records: NewRecord | Iterable[NewRecord],
+        checks: StreamStateCheck | Iterable[StreamStateCheck] | None = None,
+        *,
+        timeout: float | None = None,
+        credentials: grpc.CallCredentials | None = None,
+    ) -> AppendRecordsResult:  # pragma: <26.1 no cover
+        """
+        Appends new events to one or many streams.
+        """
+        timeout = timeout if timeout is not None else self._default_deadline
+        if isinstance(records, NewRecord):
+            records = [records]
+        if isinstance(checks, StreamStateCheck):
+            checks = [checks]
+        return await self.connection.v2streams.append_records(
+            records=records,
+            checks=checks,
+            timeout=timeout,
+            metadata=self._call_metadata,
+            credentials=credentials or self._call_credentials,
+        )
+
     @retrygrpc
     @autoreconnect
     async def read_all(
@@ -1485,6 +1520,37 @@ class AsyncKurrentDBClient(BaseKurrentDBClient):
             credentials=credentials or self._call_credentials,
         )
 
+    @overload
+    async def create_projection(
+        self,
+        *,
+        name: str,
+        query: str,
+        engine_version: Literal["v1"] = "v1",
+        emit_enabled: bool = False,
+        track_emitted_streams: bool = False,
+        timeout: float | None = None,
+        credentials: grpc.CallCredentials | None = None,
+    ) -> None:
+        """
+        Creates a projection using the v1 engine.
+        """
+
+    @overload
+    async def create_projection(
+        self,
+        *,
+        name: str,
+        query: str,
+        engine_version: Literal["v2"],
+        emit_enabled: bool = False,
+        timeout: float | None = None,
+        credentials: grpc.CallCredentials | None = None,
+    ) -> None:
+        """
+        Creates a projection using the v2 engine.
+        """
+
     @retrygrpc
     @autoreconnect
     async def create_projection(
@@ -1492,6 +1558,7 @@ class AsyncKurrentDBClient(BaseKurrentDBClient):
         *,
         name: str,
         query: str,
+        engine_version: Literal["v1", "v2"] = "v1",
         emit_enabled: bool = False,
         track_emitted_streams: bool = False,
         timeout: float | None = None,
@@ -1503,8 +1570,9 @@ class AsyncKurrentDBClient(BaseKurrentDBClient):
         timeout = timeout if timeout is not None else self._default_deadline
 
         await self.connection.projections.create(
-            query=query,
             name=name,
+            query=query,
+            engine_version=engine_version,
             emit_enabled=emit_enabled,
             track_emitted_streams=track_emitted_streams,
             timeout=timeout,

{kurrentdbclient-1.2.3 → kurrentdbclient-1.3.0}/kurrentdbclient/client.py

@@ -52,7 +52,15 @@ from kurrentdbclient.connection_spec import (
     ConnectionSpec,
     grpc_target,
 )
-from kurrentdbclient.events import NewEvent, NewEvents, RecordedEvent, StreamState
+from kurrentdbclient.events import (
+    ConsistencyCheck,
+    NewEvent,
+    NewEvents,
+    NewRecord,
+    RecordedEvent,
+    StreamState,
+    StreamStateCheck,
+)
 from kurrentdbclient.exceptions import (
     DiscoveryFailedError,
     FollowerNotFoundError,
@@ -85,7 +93,7 @@ if TYPE_CHECKING:
         ProjectionStatistics,
     )
     from kurrentdbclient.streams import StreamsService
-    from kurrentdbclient.v2streams import V2StreamsService
+    from kurrentdbclient.v2streams import AppendRecordsResult, V2StreamsService
 
 # Matches the 'type' of "system" events.
 KDB_SYSTEM_EVENTS_REGEX = r"\$.+"
@@ -578,6 +586,33 @@ class KurrentDBClient(BaseKurrentDBClient):
             credentials=credentials or self._call_credentials,
         )
 
+    @retrygrpc
+    @autoreconnect
+    def append_records(
+        self,
+        /,
+        records: NewRecord | Iterable[NewRecord],
+        checks: ConsistencyCheck | Iterable[ConsistencyCheck] | None = None,
+        *,
+        timeout: float | None = None,
+        credentials: grpc.CallCredentials | None = None,
+    ) -> AppendRecordsResult:  # pragma: <26.1 no cover
+        """
+        Appends new events to one or many streams.
+        """
+        timeout = timeout if timeout is not None else self._default_deadline
+        if isinstance(records, NewRecord):
+            records = [records]
+        if isinstance(checks, StreamStateCheck):
+            checks = [checks]
+        return self.v2streams.append_records(
+            records=records,
+            checks=checks,
+            timeout=timeout,
+            metadata=self._call_metadata,
+            credentials=credentials or self._call_credentials,
+        )
+
     @retrygrpc
     @autoreconnect
     def delete_stream(
@@ -1803,6 +1838,37 @@ class KurrentDBClient(BaseKurrentDBClient):
             credentials=credentials or self._call_credentials,
         )
 
+    @overload
+    def create_projection(
+        self,
+        *,
+        name: str,
+        query: str,
+        engine_version: Literal["v1"] = "v1",
+        emit_enabled: bool = False,
+        track_emitted_streams: bool = False,
+        timeout: float | None = None,
+        credentials: grpc.CallCredentials | None = None,
+    ) -> None:
+        """
+        Creates a projection using the v1 engine.
+        """
+
+    @overload
+    def create_projection(
+        self,
+        *,
+        name: str,
+        query: str,
+        engine_version: Literal["v2"],
+        emit_enabled: bool = False,
+        timeout: float | None = None,
+        credentials: grpc.CallCredentials | None = None,
+    ) -> None:
+        """
+        Creates a projection using the v2 engine.
+        """
+
     @retrygrpc
     @autoreconnect
     def create_projection(
@@ -1810,6 +1876,7 @@ class KurrentDBClient(BaseKurrentDBClient):
         *,
         name: str,
         query: str,
+        engine_version: Literal["v1", "v2"] = "v1",
         emit_enabled: bool = False,
         track_emitted_streams: bool = False,
         timeout: float | None = None,
@@ -1821,8 +1888,9 @@ class KurrentDBClient(BaseKurrentDBClient):
         timeout = timeout if timeout is not None else self._default_deadline
 
         self.projections.create(
-            query=query,
             name=name,
+            query=query,
+            engine_version=engine_version,
             emit_enabled=emit_enabled,
             track_emitted_streams=track_emitted_streams,
             timeout=timeout,

{kurrentdbclient-1.2.3 → kurrentdbclient-1.3.0}/kurrentdbclient/common.py

@@ -7,7 +7,7 @@ import os
 import threading
 from abc import ABC, abstractmethod
 from base64 import b64encode
-from collections.abc import AsyncIterator, Iterator, Sequence
+from collections.abc import AsyncIterator, Iterable, Iterator, Sequence
 from contextlib import AbstractAsyncContextManager, AbstractContextManager
 from typing import (
     TYPE_CHECKING,
@@ -31,6 +31,8 @@ from kurrentdbclient.exceptions import (
     AbortedByServerError,
     AlreadyExistsError,
     CancelledByClientError,
+    ConsistencyCheckFailure,
+    ConsistencyChecksFailedError,
     ConsumerTooSlowError,
     ExceptionThrownByHandlerError,
     FailedPreconditionError,
@@ -47,6 +49,7 @@ from kurrentdbclient.exceptions import (
     RecordMaxSizeExceededError,
     ServiceUnavailableError,
     SSLError,
+    StreamStateCheckFailure,
     StreamTombstonedError,
     TransactionMaxSizeExceededError,
     UnauthenticatedError,
@@ -239,7 +242,7 @@ def handle_rpc_error(e: grpc.RpcError) -> KurrentDBClientError:  # noqa: PLR0911
                                 "actual", "current"
                             ),
                             stream_name=unpacked_detail.stream,
-                            current_version=unpacked_detail.actual_revision,
+                            actual_version=unpacked_detail.actual_revision,
                             expected_version=unpacked_detail.expected_revision,
                         )
                     if isinstance(
@@ -249,6 +252,16 @@ def handle_rpc_error(e: grpc.RpcError) -> KurrentDBClientError:  # noqa: PLR0911
                         return StreamTombstonedError(
                             rich_status.message, stream_name=unpacked_detail.stream
                         )
+                    if isinstance(
+                        unpacked_detail,
+                        v2streams_errors_pb2.AppendConsistencyViolationErrorDetails,
+                    ):
+                        return ConsistencyChecksFailedError(
+                            rich_status.message,
+                            failures=_convert_append_consistency_violations(
+                                unpacked_detail.violations
+                            ),
+                        )
                 if status_msg.code == grpc.StatusCode.INVALID_ARGUMENT:  # noqa: SIM102
                     if isinstance(
                         unpacked_detail,
@@ -381,6 +394,29 @@ def handle_rpc_error(e: grpc.RpcError) -> KurrentDBClientError:  # noqa: PLR0911
     return GrpcError(str(e))
 
 
+def _convert_append_consistency_violations(
+    violations: Iterable[v2streams_errors_pb2.ConsistencyViolation],
+) -> tuple[ConsistencyCheckFailure, ...]:
+    failures = []
+    for violation in violations:
+        which_type = violation.WhichOneof("type")
+        if which_type == "stream_state":
+            stream_state_violation = violation.stream_state
+            failures.append(
+                ConsistencyCheckFailure(
+                    check_index=violation.check_index,
+                    stream_state_failure=StreamStateCheckFailure(
+                        stream_name=stream_state_violation.stream,
+                        expected_state=stream_state_violation.expected_state,
+                        actual_state=stream_state_violation.actual_state,
+                    ),
+                )
+            )
+        else:  # pragma: no cover
+            pass
+    return tuple(failures)
+
+
 class KurrentDBService(Generic[TGrpcStreamers]):
     def __init__(
         self,

{kurrentdbclient-1.2.3 → kurrentdbclient-1.3.0}/kurrentdbclient/events.py

@@ -47,6 +47,32 @@ class NewEvents:
     current_version: int | StreamState
 
 
+@dataclass(frozen=True)
+class NewRecord:
+    """
+    Encapsulates event data to be recorded in KurrentDB.
+    """
+
+    stream_name: str
+    type: str
+    data: bytes
+    metadata: bytes = b""
+    content_type: ContentType = "application/json"
+    id: UUID = field(default_factory=uuid4)
+
+    def __eq__(self, other: object) -> bool:  # pragma: no cover
+        return isinstance(other, NewRecord) and self.id == other.id
+
+
+@dataclass(frozen=True)
+class StreamStateCheck:
+    stream_name: str
+    expected_state: StreamState | int
+
+
+ConsistencyCheck = StreamStateCheck  #  ... | QueryPredicateCheck
+
+
 @dataclass(frozen=True)
 class RecordedEvent:
     """

{kurrentdbclient-1.2.3 → kurrentdbclient-1.3.0}/kurrentdbclient/exceptions.py

@@ -1,9 +1,12 @@
 from __future__ import annotations
 
+from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
 from typing_extensions import deprecated
 
+from kurrentdbclient.events import StreamState
+
 if TYPE_CHECKING:
     from typing import Any
     from uuid import UUID
@@ -104,15 +107,26 @@ class WrongCurrentVersionError(KurrentDBClientError):
         self,
         *args: Any,
         stream_name: str | None = None,
-        current_version: int | None = None,
-        expected_version: int | None = None,
+        actual_version: int | StreamState | None = None,
+        expected_version: int | StreamState | None = None,
     ) -> None:
         self.stream_name = stream_name
-        self.current_version = current_version
-        self.expected_version = expected_version
+        self.actual_version = MAPPING_INT_TO_STREAM_STATE.get(
+            actual_version, actual_version
+        )
+        self.expected_version = MAPPING_INT_TO_STREAM_STATE.get(
+            expected_version, expected_version
+        )
         super().__init__(*args)
 
 
+MAPPING_INT_TO_STREAM_STATE: dict[int | StreamState | None, StreamState] = {
+    -1: StreamState.NO_STREAM,
+    -2: StreamState.ANY,
+    -4: StreamState.EXISTS,
+}
+
+
 class AccessDeniedError(KurrentDBClientError):
     """
     Raised when access is denied by the server.
@@ -331,3 +345,28 @@ class InvalidCommitPositionError(KurrentDBClientError):
     """
     Raised when reading from an commit position that does not exist.
     """
+
+
+class ConsistencyChecksFailedError(KurrentDBClientError):
+    """
+    Raised when appending records with a consistency check that fails.
+    """
+
+    def __init__(
+        self, *args: Any, failures: tuple[ConsistencyCheckFailure, ...]
+    ) -> None:
+        self.failures = failures
+        super().__init__(*args)
+
+
+@dataclass(frozen=True)
+class ConsistencyCheckFailure:
+    check_index: int
+    stream_state_failure: StreamStateCheckFailure | None
+
+
+@dataclass(frozen=True)
+class StreamStateCheckFailure:
+    stream_name: str
+    expected_state: int
+    actual_state: int

{kurrentdbclient-1.2.3 → kurrentdbclient-1.3.0}/kurrentdbclient/projections.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal
 
 import grpc
 import grpc.aio
@@ -68,17 +68,34 @@ class BaseProjectionsService(KurrentDBService[TGrpcStreamers]):
     @staticmethod
     def _construct_create_req(
         *,
-        query: str,
         name: str,
+        query: str,
+        engine_version: Literal["v1", "v2"],
         emit_enabled: bool,
         track_emitted_streams: bool,
     ) -> projections_pb2.CreateReq:
+        # Decide engine version.
+        if engine_version == "v1":
+            engine_version_option = 0
+        elif engine_version == "v2":  # pragma: <26.1 no cover
+            engine_version_option = 1
+        else:
+            msg = (
+                f"Unsupported projection engine version "
+                f"(hint: use 'v1' or 'v2'): {engine_version}"
+            )
+            raise ValueError(msg)
+        # Defend server against invalid requests.
+        if engine_version == "v2" and track_emitted_streams:  # pragma: <26.1 no cover
+            msg = "Tracking emitted streams is not supported with engine version 2."
+            raise ValueError(msg)
         options = projections_pb2.CreateReq.Options(
             continuous=projections_pb2.CreateReq.Options.Continuous(
                 name=name,
                 emit_enabled=emit_enabled,
                 track_emitted_streams=track_emitted_streams,
             ),
+            engine_version=engine_version_option,
             query=query,
         )
         return projections_pb2.CreateReq(options=options)
@@ -261,8 +278,9 @@ class AsyncProjectionsService(BaseProjectionsService[AsyncGrpcStreamers]):
     async def create(
         self,
         *,
-        query: str,
         name: str,
+        query: str,
+        engine_version: Literal["v1", "v2"],
         emit_enabled: bool,
         track_emitted_streams: bool,
         timeout: float | None = None,
@@ -270,8 +288,9 @@ class AsyncProjectionsService(BaseProjectionsService[AsyncGrpcStreamers]):
         credentials: grpc.CallCredentials | None = None,
     ) -> None:
         create_req = self._construct_create_req(
-            query=query,
             name=name,
+            query=query,
+            engine_version=engine_version,
             emit_enabled=emit_enabled,
             track_emitted_streams=track_emitted_streams,
         )
@@ -541,8 +560,9 @@ class ProjectionsService(BaseProjectionsService[GrpcStreamers]):
     def create(
         self,
         *,
-        query: str,
         name: str,
+        query: str,
+        engine_version: Literal["v1", "v2"] = "v1",
         emit_enabled: bool,
         track_emitted_streams: bool,
         timeout: float | None = None,
@@ -550,8 +570,9 @@ class ProjectionsService(BaseProjectionsService[GrpcStreamers]):
         credentials: grpc.CallCredentials | None = None,
     ) -> None:
         create_req = self._construct_create_req(
-            query=query,
             name=name,
+            query=query,
+            engine_version=engine_version,
             emit_enabled=emit_enabled,
             track_emitted_streams=track_emitted_streams,
         )

{kurrentdbclient-1.2.3 → kurrentdbclient-1.3.0}/kurrentdbclient/protos/google/rpc/code_pb2.pyi

@@ -16,25 +16,25 @@ See the License for the specific language governing permissions and
 limitations under the License.
 """
 
-import builtins
-import google.protobuf.descriptor
-import google.protobuf.internal.enum_type_wrapper
+from google.protobuf import descriptor as _descriptor
+from google.protobuf.internal import enum_type_wrapper as _enum_type_wrapper
+import builtins as _builtins
 import sys
-import typing
+import typing as _typing
 
 if sys.version_info >= (3, 10):
-    import typing as typing_extensions
+    from typing import TypeAlias as _TypeAlias
 else:
-    import typing_extensions
+    from typing_extensions import TypeAlias as _TypeAlias
 
-DESCRIPTOR: google.protobuf.descriptor.FileDescriptor
+DESCRIPTOR: _descriptor.FileDescriptor
 
 class _Code:
-    ValueType = typing.NewType("ValueType", builtins.int)
-    V: typing_extensions.TypeAlias = ValueType
+    ValueType = _typing.NewType("ValueType", _builtins.int)
+    V: _TypeAlias = ValueType  # noqa: Y015
 
-class _CodeEnumTypeWrapper(google.protobuf.internal.enum_type_wrapper._EnumTypeWrapper[_Code.ValueType], builtins.type):
-    DESCRIPTOR: google.protobuf.descriptor.EnumDescriptor
+class _CodeEnumTypeWrapper(_enum_type_wrapper._EnumTypeWrapper[_Code.ValueType], _builtins.type):
+    DESCRIPTOR: _descriptor.EnumDescriptor
     OK: _Code.ValueType  # 0
     """Not an error; returned on success.
 
@@ -354,4 +354,4 @@ DATA_LOSS: Code.ValueType  # 15
 
 HTTP Mapping: 500 Internal Server Error
 """
-global___Code = Code
+Global___Code: _TypeAlias = Code  # noqa: Y015

{kurrentdbclient-1.2.3 → kurrentdbclient-1.3.0}/kurrentdbclient/protos/google/rpc/code_pb2_grpc.py

@@ -4,7 +4,7 @@ import grpc
 import warnings
 
 
-GRPC_GENERATED_VERSION = '1.75.1'
+GRPC_GENERATED_VERSION = '1.80.0'
 GRPC_VERSION = grpc.__version__
 _version_not_supported = False
 
@@ -17,7 +17,7 @@ except ImportError:
 if _version_not_supported:
     raise RuntimeError(
         f'The grpc package installed is at version {GRPC_VERSION},'
-        + f' but the generated code in kurrentdbclient/protos/google/rpc/code_pb2_grpc.py depends on'
+        + ' but the generated code in kurrentdbclient/protos/google/rpc/code_pb2_grpc.py depends on'
         + f' grpcio>={GRPC_GENERATED_VERSION}.'
         + f' Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}'
         + f' or downgrade your generated code using grpcio-tools<={GRPC_VERSION}.'