python-event-sourcery 0.6.2a1__tar.gz → 0.7.0__tar.gz

{python_event_sourcery-0.6.2a1 → python_event_sourcery-0.7.0}/AGENTS.md

@@ -5,7 +5,7 @@ Event sourcing library for Python with pluggable backends.
 ## Layout
 
 - `event_sourcery/` — core library
-- `event_sourcery_sqlalchemy/`, `event_sourcery_django/`, `event_sourcery_kurrentdb/` — backends (optional extras: `sqlalchemy`, `django`, `kurrentdb`)
+- `event_sourcery_sqlalchemy/`, `event_sourcery_django/`, `event_sourcery_kurrentdb/` — backends (optional extras: `sqlalchemy`, `sqlalchemy-async`, `django`, `kurrentdb`)
 - `tests/` — shared test suite run against every backend
 - `docs/` — documentation (zensical)
 

python_event_sourcery-0.7.0/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+## 0.7.0
+### Added
+- Async API mirroring the sync one: `AsyncEventStore`, `AsyncBackend`, `AsyncOutbox`,
+  `AsyncRepository`, `AsyncProjector`, `AsyncEncryption` and friends.
+- Async backends: in-memory, `AsyncSQLAlchemyBackend` (new `sqlalchemy-async` extra)
+  and `AsyncKurrentDBBackend`.
+
+### Changed
+- **Breaking:** `expected_version` is enforced on every append. The default `0` now
+  means "stream must not exist", so appending to an existing stream requires its
+  current version (or `NO_VERSIONING`); a non-zero version on a new stream is rejected.
+  Previously both cases were silently accepted.
+- **Breaking:** KurrentDB checks `expected_version` server-side, closing the race
+  between version check and append.
+- **Breaking (Django):** migration `0002` adds a unique constraint on
+  `(stream, version)`. Duplicates, possible under the previous lenient versioning,
+  make it stop with a list of affected streams; nothing is changed until they are
+  resolved. Find them with:
+  `SELECT stream_id, version FROM event_sourcery_django_event
+  GROUP BY stream_id, version HAVING COUNT(*) > 1;`
+  Resolve per stream as your domain requires: renumber the events (and the stream's
+  `version`) in insertion order, or delete the duplicates. Building the index blocks
+  writes to the events table for its duration.
+
+### Fixes
+- Tenant isolation: in-memory streams are scoped per tenant; SQLAlchemy
+  `delete_stream`, `save_snapshot` and versioned appends no longer touch other
+  tenants' streams with the same ID.
+- Outbox preserves stream category (SQLAlchemy, Django).
+- KurrentDB outbox acknowledges events rejected by the filter instead of leaving
+  them to be redelivered.
+- In-memory backend no longer persists events whose deserialization fails;
+  in-transaction dispatcher deserializes only events with matching listeners.
+- `event_sourcery_sqlalchemy` imports on SQLAlchemy 2.1.
+
+## 0.6.1
+### Fixes
+- Include the `py.typed` marker in the `event_sourcery_otel` package.
+
+## 0.6.0
+### Added
+- Typed, independently owned event context components with lazy access through `Context.get()`.
+- Context enrichers configured through `Backend.with_context_enrichers()`.
+- Optional `event_sourcery_otel` package for OpenTelemetry context propagation and parent-context activation.
+
+### Changed
+- **Breaking:** New `Context` values reject arbitrary root fields; add new context data with typed components.
+
+## 0.5.2
+### Changed
+- **Breaking:** `Repository.aggregate()` yields `WrappedAggregate` instead of `Aggregate` directly
+
+## 0.5.1
+### Added
+- In transaction subscription to category
+- Custom context support in `Repository.aggregate()` via optional `context` parameter
+- `WrappedEvent.get_context()` method for typed context retrieval
+### Fixes
+- event_sourcery_sqlalchemy.configure_models annotation for sqlalchemy.orm.DeclarativeBase
+
+## 0.5.0
+### Added
+- Event definitions via the `Event` base class (Pydantic) with built-in metadata and tracing IDs.
+- Event Store API for appending/loading streams with optimistic concurrency and optional `NO_VERSIONING`.
+- Stream snapshots to optimize long event streams.
+- Outbox pattern with retries and optional filters, plus synchronous in-process subscriptions.
+- Subscription builder with single-event and batch iterators for asynchronous processing.
+- Multi-tenancy with tenant-scoped stores and explicit visibility rules.
+- Crypto-shredding and field-level encryption via `Encrypted` and `DataSubject` markers.
+- Event sourcing primitives: `Aggregate` and `Repository` base classes.
+- Backend integrations for SQLAlchemy, Django, KurrentDB (EventStoreDB), and in-memory storage.

{python_event_sourcery-0.6.2a1 → python_event_sourcery-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-event-sourcery
-Version: 0.6.2a1
+Version: 0.7.0
 Summary: A library for event-based systems in Python.
 Author-email: Sebastian Buczyński <nnplaya@gmail.com>, Łukasz Żukowski <lukasz.zukowski@gmail.com>
 License-Expression: MIT
@@ -17,6 +17,8 @@ Provides-Extra: otel
 Requires-Dist: opentelemetry-api<2,>=1; extra == 'otel'
 Provides-Extra: sqlalchemy
 Requires-Dist: sqlalchemy>=2.0; extra == 'sqlalchemy'
+Provides-Extra: sqlalchemy-async
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'sqlalchemy-async'
 Description-Content-Type: text/markdown
 
 
@@ -91,7 +93,7 @@ from event_sourcery import (
 
 # Set up your DB and application as you would normally do
 engine = create_engine(
-    "postgresql://event_sourcery:event_sourcery@localhost:5432/event_sourcery"
+    "postgresql+psycopg://event_sourcery:event_sourcery@localhost:5432/event_sourcery"
 )
 
 

{python_event_sourcery-0.6.2a1 → python_event_sourcery-0.7.0}/README.md

@@ -70,7 +70,7 @@ from event_sourcery import (
 
 # Set up your DB and application as you would normally do
 engine = create_engine(
-    "postgresql://event_sourcery:event_sourcery@localhost:5432/event_sourcery"
+    "postgresql+psycopg://event_sourcery:event_sourcery@localhost:5432/event_sourcery"
 )
 
 

python_event_sourcery-0.7.0/docs/adr/20260827-async-api.md

@@ -0,0 +1,133 @@
+# Async API
+
+Date: 2026-08-27
+
+## Status
+
+Accepted
+
+## Context
+
+Applications built on async frameworks (FastAPI, aiohttp, async workers) need
+an event store that does not block the event loop. We want to add async support
+without breaking or degrading the existing synchronous API, which remains fully
+supported.
+
+## Decision
+
+**Parallel async classes.** Every component gets an async counterpart with the
+`Async` prefix: `AsyncEventStore`, `AsyncBackend`, `AsyncOutbox`,
+`AsyncSubscriptionBuilder`, `AsyncStorageStrategy`, etc. Synchronous classes are
+untouched. We deliberately rejected `a`-prefixed methods on shared classes to
+keep contracts explicit and make accidental sync/async mixing impossible.
+
+**Public layout mirrors the sync one.** Implementation lives in the private
+`event_sourcery._event_store._async` subpackage; public proxy imports live in
+`event_sourcery.async_` (following the packaging ADR). Root `event_sourcery`
+exports the four main symbols, same as sync: `AsyncEventStore`, `AsyncBackend`,
+`AsyncOutbox`, `AsyncTransactionalBackend`.
+
+**Asyncio-only.** The public async contract targets asyncio. No trio/anyio
+support is promised.
+
+**Deliberate API deviations from sync:**
+
+- `position` is a coroutine method — `await store.position()` — because
+  fetching the position performs I/O in real backends. Same applies to
+  `AsyncStorageStrategy.current_position`.
+- Subscriptions return `AsyncIterator`; outbox entries are async context
+  managers; outbox publishers are async callables.
+- **In-transaction listeners remain synchronous** even on async backends. They
+  are dispatched inside the append transaction, where bridging to async
+  callables would either block the loop or break ordering guarantees.
+- KurrentDB outbox creates its persistent subscription lazily (sync variant
+  creates it eagerly in `with_outbox()`, which cannot await). Because the
+  subscription is anchored at creation time (`from_end=True`), the async
+  backend ensures creation before the first append that uses the outbox —
+  creating it only on the first outbox run would permanently skip events
+  appended earlier.
+- SQLAlchemy async strategies avoid ORM relationship arms
+  (`stream.events.extend(...)`, `stream.snapshots.append(...)`) and lazy
+  attribute access: both trigger lazy loads, which are synchronous I/O and
+  raise `MissingGreenlet` under asyncio. Instead, foreign keys are assigned
+  directly (`entry._db_stream_id = stream.id`, producing identical INSERT
+  statements) and query results eager-load streams with `selectinload`.
+  For the same reason, the stream row found by `_ensure_stream` is passed to
+  `insert_events` directly instead of being looked up again in
+  `session.info["strong_set"]` — after a commit, the session expires ORM
+  instances and reading attributes of an expired instance would refresh
+  them lazily.
+- A single `AsyncSession` cannot interleave concurrent operations. Async
+  SQLAlchemy usage follows the same rule as the sync one: one session (and
+  thus one configured backend) per concurrent unit of work.
+- The async SQLAlchemy backend ships as a new `sqlalchemy-async` extra
+  (`SQLAlchemy[asyncio]`). Async drivers (`asyncpg`, `aiosqlite`) are not
+  installed by the library — the same policy as the sync variant, which
+  installs no database drivers either.
+
+**Testing strategy.** The shared test suite is not duplicated: async backends
+are added as fixtures next to their sync counterparts, and a sync facade
+(`tests/adapter.py`) drains coroutines on a dedicated event loop, so every
+existing BDD-style test exercises both APIs. A small set of true-async tests
+verifies concurrency semantics directly. Coverage gate stays at 100%.
+
+## Consequences
+
+- Sync and async APIs evolve in parallel; every new feature must land in both.
+- Docs show sync and async snippets side by side (tabs); docs tests use the
+  in-memory backend only, so no docker services are needed.
+- Async variants of SQLAlchemy and KurrentDB backends follow in subsequent
+  milestones; Django async is currently out of scope.
+
+## Amendment 2026-08-27: SQLAlchemy backend milestone
+
+The SQLAlchemy milestone validated the decisions above against a real
+relational backend. Consequences specific to it:
+
+- The mirrored test suite runs against `sqlalchemy_async_sqlite` and
+  `sqlalchemy_async_postgres` fixtures through the sync facade. Test
+  transactions are never committed, so fixture teardown closes all tracked
+  sessions before dropping tables (mirroring the sync suite's
+  `close_all_sessions()`) — otherwise `DROP TABLE` deadlocks against locks
+  held by open transactions.
+- In-transaction listeners fired inside the append transaction work unchanged:
+  the async dispatcher awaits deserialization before invoking synchronous listeners.
+
+## Amendment 2026-08-28: parity wrap-up
+
+Milestone 4 closed the remaining gaps, with two notable designs:
+
+- **Async encryption pipeline.** `AsyncEncryption` /
+  `AsyncEncryptionKeyStorageStrategy` mirror their sync counterparts;
+  `AsyncSerde` exclusively awaits an `AsyncEncryption`.
+  `AsyncBackend.with_encryption` accepts only async key storage. The async
+  in-transaction dispatcher awaits deserialization, then invokes synchronous
+  listeners. Sync backends retain their separate synchronous pipeline.
+- **In-transaction dispatcher only deserializes on matching listeners.**
+  `Dispatcher` resolves event types lazily via `EventRegistry`, which keeps
+  the (possibly stubbed) serde untouched when no listener is registered.
+- `AsyncRepository`, `AsyncProjector`, `AsyncCursorsDao`,
+  `AsyncReadModel`, `AsyncSqlAlchemyCursorsDao` complete the feature parity.
+
+### Parity audit (sync → async)
+
+| Sync | Async (or documented exclusion) |
+|---|---|
+| `Backend` / `TransactionalBackend` | `AsyncBackend` / `AsyncTransactionalBackend` |
+| `EventStore` | `AsyncEventStore` |
+| `Outbox` (`run`) | `AsyncOutbox` (`run`) |
+| `StorageStrategy` | `AsyncStorageStrategy` |
+| `SubscriptionStrategy` | `AsyncSubscriptionStrategy` |
+| `OutboxStorageStrategy` | `AsyncOutboxStorageStrategy` |
+| `PositionPhase` / `FilterPhase` / `BuildPhase` | async counterparts |
+| `SubscriptionBuilder` | `AsyncSubscriptionBuilder` |
+| `NoKeyStorageStrategy` | `AsyncNoKeyStorageStrategy` |
+| `Encryption` | `AsyncEncryption` (shred via `ashred`) |
+| `EncryptionKeyStorageStrategy` | `AsyncEncryptionKeyStorageStrategy` |
+| `Repository` | `AsyncRepository` |
+| `CursorsDao` | `AsyncCursorsDao` |
+| `Projector` | `AsyncProjector` |
+| `ReadModel` (callable) | `AsyncReadModel` (async callable) |
+| `SqlAlchemyCursorsDao` | `AsyncSqlAlchemyCursorsDao` |
+| `InMemoryBackend` / `InMemoryKeyStorage` | `Async*` counterparts |
+| `In-transaction listeners` | remain sync (ADR §2.4), dispatched under lazy resolution |

python_event_sourcery-0.7.0/docs/code/recipes/integrate/kurrent_async_01.py

@@ -0,0 +1,15 @@
+import asyncio
+
+from kurrentdbclient import AsyncKurrentDBClient
+
+from event_sourcery import StreamId
+from event_sourcery_kurrentdb.async_ import AsyncKurrentDBBackend
+
+
+async def main() -> None:
+    client = AsyncKurrentDBClient(uri="kurrentdb://localhost:2113?Tls=false")
+    backend = AsyncKurrentDBBackend().configure(client)
+    await backend.event_store.load_stream(StreamId())  # test if connection works
+
+
+asyncio.run(main())

python_event_sourcery-0.7.0/docs/code/test_get_started.py

@@ -0,0 +1,67 @@
+def test_get_started():
+    # --8<-- [start:get_started_01]
+    from event_sourcery import StreamId
+    from event_sourcery.backend import InMemoryBackend
+    from event_sourcery.event import Event
+
+    class InvoicePaid(Event):
+        invoice_number: str
+
+    backend = InMemoryBackend()
+    event_store = backend.event_store
+
+    event_store.append(
+        InvoicePaid(invoice_number="1003"),
+        stream_id=StreamId(name="invoices/1003"),
+    )
+    # --8<-- [end:get_started_01]
+    # --8<-- [start:get_started_02]
+    recorded_events = event_store.load_stream(StreamId(name="invoices/1003"))
+    for recorded in recorded_events:
+        print(recorded.event, recorded.version)
+    # --8<-- [end:get_started_02]
+
+    events = event_store.load_stream(StreamId(name="invoices/1003"))
+    assert len(events) == 1
+    assert events[0].event.invoice_number == "1003"
+    assert events[0].version == 1
+
+
+def test_get_started_async():
+    # --8<-- [start:get_started_async_01]
+    import asyncio
+
+    from event_sourcery import StreamId
+    from event_sourcery.async_.backend import AsyncInMemoryBackend
+    from event_sourcery.event import Event
+
+    class InvoicePaid(Event):
+        invoice_number: str
+
+    backend = AsyncInMemoryBackend()
+    event_store = backend.event_store
+
+    async def main() -> None:
+        await event_store.append(
+            InvoicePaid(invoice_number="1003"),
+            stream_id=StreamId(name="invoices/1003"),
+        )
+
+    asyncio.run(main())
+
+    # --8<-- [end:get_started_async_01]
+    # --8<-- [start:get_started_async_02]
+    async def read() -> None:
+        recorded_events = await event_store.load_stream(
+            StreamId(name="invoices/1003"),
+        )
+        for recorded in recorded_events:
+            print(recorded.event, recorded.version)
+
+    asyncio.run(read())
+    # --8<-- [end:get_started_async_02]
+
+    events = asyncio.run(event_store.load_stream(StreamId(name="invoices/1003")))
+    assert len(events) == 1
+    assert events[0].event.invoice_number == "1003"
+    assert events[0].version == 1