eventsourcingdb 0.8.2__tar.gz

eventsourcingdb-0.8.2/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 the native web GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

eventsourcingdb-0.8.2/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.3
+Name: eventsourcingdb
+Version: 0.8.2
+Summary: eventsourcingdb is the official client for EventSourcingDB.
+License: MIT
+Author: the native web GmbH
+Author-email: hello@thenativeweb.io
+Requires-Python: >=3.13,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: aiohttp (==3.11.13)
+Description-Content-Type: text/markdown
+
+# eventsourcingdb
+
+eventsourcingdb is the official client for EventSourcingDB.
+

eventsourcingdb-0.8.2/README.md

@@ -0,0 +1,3 @@
+# eventsourcingdb
+
+eventsourcingdb is the official client for EventSourcingDB.

eventsourcingdb-0.8.2/eventsourcingdb/__init__.py

@@ -0,0 +1,2 @@
+from .client import Client as EsdbClient
+from .client_options import ClientOptions as EsdbClientOptions

eventsourcingdb-0.8.2/eventsourcingdb/abstract_base_client.py

@@ -0,0 +1,9 @@
+from abc import ABC, abstractmethod
+from .http_client.http_client import HttpClient
+
+
+class AbstractBaseClient(ABC):
+    @property
+    @abstractmethod
+    def http_client(self) -> HttpClient:
+        raise NotImplementedError()

eventsourcingdb-0.8.2/eventsourcingdb/client.py

@@ -0,0 +1,93 @@
+from collections.abc import AsyncGenerator
+
+from .abstract_base_client import AbstractBaseClient
+from .client_configuration import ClientConfiguration
+from .client_options import ClientOptions
+from .event.event_candidate import EventCandidate
+from .event.event_context import EventContext
+from .handlers.observe_events.observe_events import observe_events
+from .handlers.observe_events.observe_events_options import ObserveEventsOptions
+from .handlers.read_event_types.event_type import EventType
+from .handlers.read_event_types.read_event_types import read_event_types
+from .handlers.register_event_schema.register_event_schema import register_event_schema
+from .http_client.http_client import HttpClient
+from .handlers.ping import ping
+from .handlers.read_events import read_events, ReadEventsOptions
+from .handlers.read_subjects import read_subjects
+from .handlers.store_item import StoreItem
+from .handlers.write_events import Precondition, write_events
+
+
+# pylint: disable=R6007
+# Reason: This class explicitly specifies the return type as None
+# for better readability. Even though it is not necessary,
+# it makes the return type clear without needing to read any
+# documentation or code.
+class Client(AbstractBaseClient):
+    def __init__(
+        self,
+        base_url: str,
+        access_token: str,
+        options: ClientOptions = ClientOptions()
+    ):
+        configuration = ClientConfiguration(
+            base_url=base_url,
+            timeout_seconds=options.timeout_seconds,
+            access_token=access_token,
+            protocol_version=options.protocol_version,
+            max_tries=options.max_tries
+        )
+
+        self.__http_client = HttpClient(configuration)
+
+    async def initialize(self) -> None:
+        await self.__http_client.initialize()
+
+    async def close(self) -> None:
+        await self.__http_client.close()
+
+    @property
+    def http_client(self) -> HttpClient:
+        return self.__http_client
+
+    async def ping(self) -> None:
+        return await ping(self)
+
+    async def read_subjects(
+        self,
+        base_subject: str
+    ) -> AsyncGenerator[str, None]:
+        async for subject in read_subjects(self, base_subject):
+            yield subject
+
+    async def read_events(
+        self,
+        subject: str,
+        options: ReadEventsOptions
+    ) -> AsyncGenerator[StoreItem, None]:
+        async for event in read_events(self, subject, options):
+            yield event
+
+    async def read_event_types(self) -> AsyncGenerator[EventType, None]:
+        async for event_type in read_event_types(self):
+            yield event_type
+
+    async def register_event_schema(self, event_type: str, json_schema: str) -> None:
+        await register_event_schema(self, event_type, json_schema)
+
+    async def observe_events(
+        self,
+        subject: str,
+        options: ObserveEventsOptions
+    ) -> AsyncGenerator[StoreItem, None]:
+        async for event in observe_events(self, subject, options):
+            yield event
+
+    async def write_events(
+        self,
+        event_candidates: list[EventCandidate],
+        preconditions: list[Precondition] = None
+    ) -> list[EventContext]:
+        if preconditions is None:
+            preconditions = []
+        return await write_events(self, event_candidates, preconditions)

eventsourcingdb-0.8.2/eventsourcingdb/client_configuration.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class ClientConfiguration:
+    base_url: str
+    timeout_seconds: int
+    access_token: str
+    protocol_version: str
+    max_tries: int

eventsourcingdb-0.8.2/eventsourcingdb/client_options.py

@@ -0,0 +1,8 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class ClientOptions:
+    timeout_seconds: int = 10
+    protocol_version: str = '1.0.0'
+    max_tries: int = 10

eventsourcingdb-0.8.2/eventsourcingdb/errors/client_error.py

@@ -0,0 +1,6 @@
+from .custom_error import CustomError
+
+
+class ClientError(CustomError):
+    def __init__(self, cause: str):
+        super().__init__(f'Client error occurred: {cause}')

eventsourcingdb-0.8.2/eventsourcingdb/errors/custom_error.py

@@ -0,0 +1,2 @@
+class CustomError(Exception):
+    pass

eventsourcingdb-0.8.2/eventsourcingdb/errors/internal_error.py

@@ -0,0 +1,6 @@
+from .custom_error import CustomError
+
+
+class InternalError(CustomError):
+    def __init__(self, cause: str):
+        super().__init__(f'Internal error occurred: {cause}')

eventsourcingdb-0.8.2/eventsourcingdb/errors/invalid_parameter_error.py

@@ -0,0 +1,7 @@
+from .custom_error import CustomError
+
+
+class InvalidParameterError(CustomError):
+    def __init__(self, parameter_name: str, reason: str):
+        super().__init__(
+            f'Parameter \'{parameter_name}\' is invalid: {reason}')

eventsourcingdb-0.8.2/eventsourcingdb/errors/server_error.py

@@ -0,0 +1,6 @@
+from .custom_error import CustomError
+
+
+class ServerError(CustomError):
+    def __init__(self, cause: str):
+        super().__init__(f'Server error occurred: {cause}')

eventsourcingdb-0.8.2/eventsourcingdb/errors/validation_error.py

@@ -0,0 +1,6 @@
+from .custom_error import CustomError
+
+
+class ValidationError(CustomError):
+    def __init__(self, cause: str):
+        super().__init__(f'Validation error occurred: {cause}')

eventsourcingdb-0.8.2/eventsourcingdb/event/event.py

@@ -0,0 +1,71 @@
+from datetime import datetime
+from typing import TypeVar
+
+from ..errors.validation_error import ValidationError
+from .event_context import EventContext
+
+Self = TypeVar("Self", bound="Event")
+
+# pylint: disable=R0917
+# Reason: This class is expected to have many parameters
+# due to its business context. Splitting it into smaller
+# methods would increase cognitive load and make the
+# code less readable.
+class Event(EventContext):
+    def __init__(
+        self,
+        data: dict,
+        source: str,
+        subject: str,
+        event_type: str,
+        spec_version: str,
+        event_id: str,
+        time: datetime,
+        data_content_type: str,
+        predecessor_hash: str,
+        trace_parent: str = None,
+        trace_state: str = None
+    ):
+        super().__init__(
+            source,
+            subject,
+            event_type,
+            spec_version,
+            event_id,
+            time,
+            data_content_type,
+            predecessor_hash,
+            trace_parent,
+            trace_state
+        )
+        self.data = data
+
+    @staticmethod
+    def parse(unknown_object: dict) -> Self:
+        event_context = super(Event, Event).parse(unknown_object)
+
+        data = unknown_object.get('data')
+        if not isinstance(data, dict):
+            raise ValidationError(
+                f'Failed to parse data \'{data}\' to object.'
+            )
+
+        return Event(
+            data,
+            event_context.source,
+            event_context.subject,
+            event_context.type,
+            event_context.spec_version,
+            event_context.event_id,
+            event_context.time,
+            event_context.data_content_type,
+            event_context.predecessor_hash,
+            event_context.trace_parent,
+            event_context.trace_state
+        )
+
+    def to_json(self):
+        json = super().to_json()
+        json['data'] = self.data
+
+        return json

eventsourcingdb-0.8.2/eventsourcingdb/event/event_candidate.py

@@ -0,0 +1,33 @@
+from dataclasses import dataclass
+
+from .validate_subject import validate_subject
+from .validate_type import validate_type
+
+
+@dataclass
+class EventCandidate:
+    source: str
+    subject: str
+    type: str
+    data: dict
+    trace_parent: str = None
+    trace_state: str = None
+
+    def validate(self) -> None:
+        validate_subject(self.subject)
+        validate_type(self.type)
+
+    def to_json(self):
+        json = {
+            'data': self.data,
+            'source': self.source,
+            'subject': self.subject,
+            'type': self.type
+        }
+
+        if self.trace_parent is not None:
+            json['traceparent'] = self.trace_parent
+        if self.trace_state is not None:
+            json['tracestate'] = self.trace_state
+
+        return json

eventsourcingdb-0.8.2/eventsourcingdb/event/event_context.py

@@ -0,0 +1,120 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import TypeVar
+
+from ..errors.internal_error import InternalError
+from ..errors.validation_error import ValidationError
+from .validate_subject import validate_subject
+from .validate_type import validate_type
+
+Self = TypeVar("Self", bound="EventContext")
+
+
+@dataclass
+class EventContext:
+    source: str
+    subject: str
+    type: str
+    spec_version: str
+    event_id: str
+    time: datetime
+    data_content_type: str
+    predecessor_hash: str
+    trace_parent: str = None
+    trace_state: str = None
+
+    @staticmethod
+    def parse(unknown_object: dict) -> Self:
+        source = unknown_object.get('source')
+        if not isinstance(source, str):
+            raise ValidationError(
+                f'Failed to parse source \'{source}\' to string.')
+
+        subject = unknown_object.get('subject')
+        if not isinstance(subject, str):
+            raise ValidationError(
+                f'Failed to parse subject \'{subject}\' to string.')
+        validate_subject(subject)
+
+        event_type = unknown_object.get('type')
+        if not isinstance(event_type, str):
+            raise ValidationError(
+                f'Failed to parse event_type \'{event_type}\' to string.')
+        validate_type(event_type)
+
+        spec_version = unknown_object.get('specversion')
+        if not isinstance(spec_version, str):
+            raise ValidationError(
+                f'Failed to parse spec_version \'{spec_version}\' to string.')
+
+        event_id = unknown_object.get('id')
+        if not isinstance(event_id, str):
+            raise ValidationError(
+                f'Failed to parse event_id \'{event_id}\' to string.')
+
+        time = unknown_object.get('time')
+        if not isinstance(time, str):
+            raise ValidationError(
+                f'Failed to parse time \'{time}\' to datetime.')
+
+        rest, sub_seconds = time.split('.')
+        sub_seconds = f'{sub_seconds[:6]:06}'
+        try:
+            time = datetime.fromisoformat(f'{rest}.{sub_seconds}')
+        except ValueError as value_error:
+            raise ValidationError(
+                f'Failed to parse time \'{time}\' to datetime.') from value_error
+        except Exception as other_error:
+            raise InternalError(str(other_error)) from other_error
+
+        data_content_type = unknown_object.get('datacontenttype')
+        if not isinstance(data_content_type, str):
+            raise ValidationError(
+                f'Failed to parse data_content_type \'{data_content_type}\' to string.')
+
+        predecessor_hash = unknown_object.get('predecessorhash')
+        if not isinstance(predecessor_hash, str):
+            raise ValidationError(
+                f'Failed to parse predecessor_hash \'{predecessor_hash}\' to string.')
+
+        trace_parent = unknown_object.get('traceparent')
+        if trace_parent is not None and not isinstance(trace_parent, str):
+            raise ValidationError(
+                f'Failed to parse trace_parent \'{trace_parent}\' to string.')
+
+        trace_state = unknown_object.get('tracestate')
+        if trace_state is not None and not isinstance(trace_state, str):
+            raise ValidationError(
+                f'Failed to parse trace_state \'{trace_state}\' to string.')
+
+        return EventContext(
+            source=source,
+            subject=subject,
+            type=event_type,
+            spec_version=spec_version,
+            event_id=event_id,
+            time=time,
+            data_content_type=data_content_type,
+            predecessor_hash=predecessor_hash,
+            trace_parent=trace_parent,
+            trace_state=trace_state,
+        )
+
+    def to_json(self):
+        json = {
+            'specversion': self.spec_version,
+            'id': self.event_id,
+            'time': self.time.isoformat(sep='T'),
+            'source': self.source,
+            'subject': self.subject,
+            'type': self.type,
+            'datacontenttype': self.data_content_type,
+            'predecessorhash': self.predecessor_hash
+        }
+
+        if self.trace_parent is not None:
+            json['traceparent'] = self.trace_parent
+        if self.trace_state is not None:
+            json['tracestate'] = self.trace_state
+
+        return json

eventsourcingdb-0.8.2/eventsourcingdb/event/source.py

@@ -0,0 +1,30 @@
+from dataclasses import dataclass
+
+from ..event.event_candidate import EventCandidate
+
+
+# pylint: disable=R0917
+# Reason: This class is expected to have many parameters
+# due to its business context. Splitting it into smaller
+# methods would increase cognitive load and make the
+# code less readable.
+@dataclass
+class Source:
+    source: str
+
+    def new_event(
+        self,
+        subject: str,
+        event_type: str,
+        data: dict,
+        trace_parent: str = None,
+        trace_state: str = None
+    ) -> EventCandidate:
+        return EventCandidate(
+            self.source,
+            subject,
+            event_type,
+            data,
+            trace_parent,
+            trace_state
+        )

eventsourcingdb-0.8.2/eventsourcingdb/event/validate_subject.py

@@ -0,0 +1,13 @@
+import re
+
+from ..errors.validation_error import ValidationError
+
+WORD_PATTERN = '[0-9A-Za-z_-]+'
+SUBJECT_PATTERN = f'^/({WORD_PATTERN}/)*({WORD_PATTERN}/?)?$'
+
+
+def validate_subject(subject: str) -> None:
+    if re.search(SUBJECT_PATTERN, subject) is None:
+        raise ValidationError(
+            f'Failed to validate subject: \'{subject}\' must be an absolute, slash-separated path.'
+        )

eventsourcingdb-0.8.2/eventsourcingdb/event/validate_type.py

@@ -0,0 +1,12 @@
+import re
+
+from ..errors.validation_error import ValidationError
+
+TYPE_PATTERN = r'^[0-9A-Za-z_-]{2,}\.(?:[0-9A-Za-z_-]+\.)+[0-9A-Za-z_-]+$'
+
+
+def validate_type(event_type: str) -> None:
+    if re.search(TYPE_PATTERN, event_type) is None:
+        raise ValidationError(
+            f'Failed to validate type: \'{event_type}\' must be a reverse domain name.'
+        )

eventsourcingdb-0.8.2/eventsourcingdb/handlers/is_heartbeat.py

@@ -0,0 +1,7 @@
+from typing import Any
+
+HEARTBEAT_TYPE = 'heartbeat'
+
+
+def is_heartbeat(message: Any) -> bool:
+    return isinstance(message, dict) and message.get('type') == HEARTBEAT_TYPE

eventsourcingdb-0.8.2/eventsourcingdb/handlers/is_item.py

@@ -0,0 +1,16 @@
+from typing import Any
+
+ITEM_TYPE = 'item'
+
+
+def is_item(message: Any) -> bool:
+    if not isinstance(message, dict) or message.get('type') != ITEM_TYPE:
+        return False
+
+    payload = message.get('payload')
+
+    return (
+        isinstance(payload, dict)
+        and isinstance(payload.get('event'), dict)
+        and isinstance(payload.get('hash'), str)
+    )

eventsourcingdb-0.8.2/eventsourcingdb/handlers/is_stream_error.py

@@ -0,0 +1,12 @@
+from typing import Any
+
+ERROR_TYPE = 'error'
+
+
+def is_stream_error(message: Any) -> bool:
+    if not isinstance(message, dict) or message.get('type') != ERROR_TYPE:
+        return False
+
+    payload = message.get('payload')
+
+    return isinstance(payload, dict) and isinstance(payload.get('error'), str)

eventsourcingdb-0.8.2/eventsourcingdb/handlers/observe_events/__init__.py

@@ -0,0 +1,4 @@
+from .observe_events import observe_events
+from .observe_events_options import ObserveEventsOptions
+from .observe_from_latest_event import ObserveFromLatestEvent
+from .if_event_is_missing_during_observe import IfEventIsMissingDuringObserve

eventsourcingdb-0.8.2/eventsourcingdb/handlers/observe_events/if_event_is_missing_during_observe.py

@@ -0,0 +1,6 @@
+from enum import Enum
+
+
+class IfEventIsMissingDuringObserve(str, Enum):
+    WAIT_FOR_EVENT = 'wait-for-event'
+    READ_EVERYTHING = 'read-everything'

eventsourcingdb-0.8.2/eventsourcingdb/handlers/observe_events/observe_events.py

@@ -0,0 +1,85 @@
+import json
+from collections.abc import AsyncGenerator
+from http import HTTPStatus
+
+from ..is_heartbeat import is_heartbeat
+from ..is_item import is_item
+from ..is_stream_error import is_stream_error
+from ..parse_raw_message import parse_raw_message
+from ...abstract_base_client import AbstractBaseClient
+from ...errors.custom_error import CustomError
+from ...errors.internal_error import InternalError
+from ...errors.invalid_parameter_error import InvalidParameterError
+from ...errors.server_error import ServerError
+from ...errors.validation_error import ValidationError
+from ...event.event import Event
+from ...event.validate_subject import validate_subject
+from ..store_item import StoreItem
+from .observe_events_options import ObserveEventsOptions
+from ...http_client.response import Response
+
+# pylint: disable=R6007
+# Reason: This method explicitly specifies the return type as None
+# for better readability. Even though it is not necessary,
+# it makes the return type clear without needing to read any
+# documentation or code.
+async def observe_events(
+    client: AbstractBaseClient,
+    subject: str,
+    options: ObserveEventsOptions
+) -> AsyncGenerator[StoreItem, None]:
+    try:
+        validate_subject(subject)
+    except ValidationError as validation_error:
+        raise InvalidParameterError('subject', str(validation_error)) from validation_error
+    except Exception as other_error:
+        raise InternalError(str(other_error)) from other_error
+
+    try:
+        options.validate()
+    except ValidationError as validation_error:
+        raise InvalidParameterError('options', str(validation_error)) from validation_error
+    except Exception as other_error:
+        raise InternalError(str(other_error)) from other_error
+
+    request_body = json.dumps({
+        'subject': subject,
+        'options': options.to_json()
+    })
+
+    response: Response
+    try:
+        response = await client.http_client.post(
+            path='/api/observe-events',
+            request_body=request_body,
+        )
+    except CustomError as custom_error:
+        raise custom_error
+    except Exception as other_error:
+        raise InternalError(str(other_error)) from other_error
+
+    with response:
+        if response.status_code != HTTPStatus.OK:
+            raise ServerError(
+                f'Unexpected response status: '
+                f'{response.status_code} {HTTPStatus(response.status_code).phrase}'
+            )
+        async for raw_message in response.body:
+            message = parse_raw_message(raw_message)
+
+            if is_heartbeat(message):
+                continue
+
+            if is_stream_error(message):
+                raise ServerError(f'{message["payload"]["error"]}.')
+
+            if is_item(message):
+                event = Event.parse(message['payload']['event'])
+
+                yield StoreItem(event, message['payload']['hash'])
+                continue
+
+            raise ServerError(
+                f'Failed to read events, an unexpected stream item was received: '
+                f'{message}.'
+            )