python-event-sourcery 0.5.3a1__tar.gz → 0.5.3a3__tar.gz

python_event_sourcery-0.5.3a3/.adr-dir

@@ -0,0 +1 @@
+docs/adr

python_event_sourcery-0.5.3a3/.github/workflows/bump-version-and-publish.yml

@@ -0,0 +1,35 @@
+name: Bump version and publish
+
+on:
+  push:
+    branches: [ main ]
+
+env:
+  PYTHON_VERSION: "3.10"
+
+jobs:
+  bump-and-publish:
+    if: github.event.head_commit.message != 'Autobump version'
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+      with:
+        python-version: ${{ env.PYTHON_VERSION }}
+        enable-cache: true
+    - name: Bump version
+      run: uv version --bump alpha
+    - uses: EndBug/add-and-commit@v9
+      with:
+        add: "pyproject.toml uv.lock"
+        author_name: Python Event Sourcery Bot
+        message: 'Autobump version'
+    - name: Publish prerelease
+      env:
+        PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+      run: |
+        uv build
+        uv publish --token $PYPI_TOKEN

python_event_sourcery-0.5.3a3/.github/workflows/deploy-docs.yml

@@ -0,0 +1,32 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+env:
+  PYTHON_VERSION: "3.10"
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          enable-cache: true
+      - name: Install deps
+        run: uv sync --all-extras
+      - name: Build docs
+        run: uv run --all-extras zensical build --clean
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site

python_event_sourcery-0.5.3a3/.github/workflows/main.yml

@@ -0,0 +1,58 @@
+name: Lint & tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [ '3.10', '3.11', '3.12', '3.13' ]
+
+    services:
+      postgres:
+        image: postgres:14
+        env:
+          POSTGRES_USER: es
+          POSTGRES_PASSWORD: es
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+
+      eventstoredb:
+        image: eventstore/eventstore:latest
+        env:
+          EVENTSTORE_MEM_DB: True
+          EVENTSTORE_CLUSTER_SIZE: 1
+          EVENTSTORE_RUN_PROJECTIONS: All
+          EVENTSTORE_START_STANDARD_PROJECTIONS: true
+          EVENTSTORE_INSECURE: true
+          EVENTSTORE_ENABLE_ATOM_PUB_OVER_HTTP: true
+        ports:
+          - 1113:1113
+          - 2113:2113
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+      with:
+        python-version: ${{ matrix.python-version }}
+        enable-cache: true
+    - name: Install deps
+      run: uv sync --all-extras
+    - name: Run linters
+      run: make lint
+    - name: Build docs
+      run: uv run --all-extras zensical build --clean
+    - name: Test with pytest
+      run: make test

python_event_sourcery-0.5.3a3/.github/workflows/publish-release.yml

@@ -0,0 +1,24 @@
+name: Publish on Release
+
+on:
+  release:
+    types: [published]
+
+env:
+  PYTHON_VERSION: "3.10"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+      - name: Publish to PyPI
+        env:
+          PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: |
+          uv build
+          uv publish --token $PYPI_TOKEN

python_event_sourcery-0.5.3a3/.gitignore

@@ -0,0 +1,129 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/

python_event_sourcery-0.5.3a3/AGENTS.md

@@ -0,0 +1,45 @@
+# AGENTS.md
+
+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`)
+- `tests/` — shared test suite run against every backend
+- `docs/` — documentation (zensical)
+
+## Tooling
+
+Package manager: **uv** (PEP 621 `pyproject.toml`, `uv.lock` committed).
+
+```bash
+uv sync --all-extras   # install all deps (dev group is included by default)
+```
+
+## Commands
+
+```bash
+docker compose up -d   # required before tests (postgres, kurrentdb, rabbitmq)
+make test              # pytest with coverage (fail_under = 100)
+make lint              # ruff format + ruff check + mypy (must pass clean)
+make docs-serve        # docs live preview
+```
+
+Run single tools via `uv run --all-extras <tool>`, e.g. `uv run --all-extras pytest tests/event_store -k django`.
+
+## Conventions
+
+- Python >= 3.10, strict mypy (`disallow_untyped_defs`), ruff line-length 88.
+- New backend functionality goes through the shared test suite in `tests/`; use `not_implemented` / `skip_backend` markers for unsupported features.
+- Version bumps: `uv version --bump alpha` (CI autopublishes prereleases on push to main).
+
+## Docs
+
+Changing public API or behavior may require updating `docs/` — pages embed runnable snippets from `docs/code/` (via `--8<--` includes). After touching docs code:
+
+```bash
+uv run --all-extras pytest docs/code   # snippets are real tests, must pass
+make lint-fix-docs                     # lint docs/code
+uv run --all-extras zensical build --clean   # verify docs build
+```

python_event_sourcery-0.5.3a3/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 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.5.3a3/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Basics
+
+## Prerequisites
+
+- docker + docker compose / any compatible replacement
+- uv
+
+## Installation
+
+```bash
+uv sync --all-extras
+```
+
+## Running tests
+
+```bash
+docker compose up
+make test
+```
+
+## Running linters
+
+```bash
+make lint
+```
+
+# Documentation
+
+First, `cd docs/documentation`
+
+## Serve docs with live preview
+
+```bash
+zensical serve
+```
+
+## Deploy docs to github pages
+
+Docs get auto deployed from main after each change.
+

python_event_sourcery-0.5.3a3/Makefile

@@ -0,0 +1,20 @@
+SRC_DIRS ?= ${wildcard event_sourcery*}
+
+.PHONY: lint
+lint:
+	uv run --all-extras ruff format $(SRC_DIRS) tests/
+	uv run --all-extras ruff check $(SRC_DIRS) tests/ --fix
+	uv run --all-extras mypy $(SRC_DIRS) tests/
+
+.PHONY: test
+test:
+	uv run --all-extras pytest $(addprefix --cov ,$(SRC_DIRS)) tests/
+
+.PHONY: docs-serve
+docs-serve:
+	uv run --all-extras zensical serve
+
+.PHONY: lint-fix-docs
+lint-fix-docs:
+	uv run --all-extras ruff format docs/code tests/
+	uv run --all-extras ruff check docs/code --fix

{python_event_sourcery-0.5.3a1 → python_event_sourcery-0.5.3a3}/PKG-INFO

@@ -1,26 +1,20 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.5
 Name: python-event-sourcery
-Version: 0.5.3a1
+Version: 0.5.3a3
 Summary: A library for event-based systems in Python.
-License: MIT
-Author: Sebastian Buczyński
-Author-email: nnplaya@gmail.com
+Author-email: Sebastian Buczyński <nnplaya@gmail.com>, Łukasz Żukowski <lukasz.zukowski@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
 Requires-Python: >=3.10
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: more-itertools
+Requires-Dist: psycopg2-binary<3,>2
+Requires-Dist: pydantic<3,>=2.0
 Provides-Extra: django
+Requires-Dist: django<6,>=4; extra == 'django'
 Provides-Extra: kurrentdb
+Requires-Dist: kurrentdbclient>=1.0.6; extra == 'kurrentdb'
 Provides-Extra: sqlalchemy
-Requires-Dist: SQLAlchemy (>=2.0) ; extra == "sqlalchemy"
-Requires-Dist: django (>=4,<6) ; extra == "django"
-Requires-Dist: kurrentdbclient (>=1.0.6) ; extra == "kurrentdb"
-Requires-Dist: more-itertools
-Requires-Dist: psycopg2-binary (>2,<3)
-Requires-Dist: pydantic (>=2.0,<3)
+Requires-Dist: sqlalchemy>=2.0; extra == 'sqlalchemy'
 Description-Content-Type: text/markdown
 
 
@@ -149,4 +143,3 @@ Anything missing? Create an issue in this repository. Let others upvote
 ## Inspirations
 - [Rails Event Store](https://railseventstore.org/)
 - [Marten](https://martendb.io/)
-

python_event_sourcery-0.5.3a3/django_manage.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python
+"""Django's command-line utility for administrative tasks."""
+import os
+import sys
+
+
+def main() -> None:
+    """Run administrative tasks."""
+    from tests.backend import django as django_backend
+    os.environ.setdefault("DJANGO_SETTINGS_MODULE", django_backend.__name__)
+    try:
+        from django.core.management import execute_from_command_line
+    except ImportError as exc:
+        raise ImportError(
+            "Couldn't import Django. Are you sure it's installed and "
+            "available on your PYTHONPATH environment variable? Did you "
+            "forget to activate a virtual environment?"
+        ) from exc
+    execute_from_command_line(sys.argv)
+
+
+if __name__ == "__main__":
+    main()

python_event_sourcery-0.5.3a3/docker-compose.yml

@@ -0,0 +1,26 @@
+services:
+  postgres:
+    image: postgres:14
+    environment:
+      POSTGRES_USER: es
+      POSTGRES_PASSWORD: es
+    ports:
+      - "5432:5432"
+
+  rabbitmq:
+    image: rabbitmq:3.11.2-management
+    ports:
+      - '5672:5672'
+      - '15672:15672'
+
+  kurrentdb:
+    image: kurrentplatform/kurrentdb
+    environment:
+      - KURRENTDB_CLUSTER_SIZE=1
+      - KURRENTDB_RUN_PROJECTIONS=All
+      - KURRENTDB_START_STANDARD_PROJECTIONS=true
+      - KURRENTDB_INSECURE=true
+      - KURRENTDB_ENABLE_ATOM_PUB_OVER_HTTP=true
+      - KURRENTDB_NODE_PORT=2113
+    ports:
+      - "2113:2113"

python_event_sourcery-0.5.3a3/docs/adr/20220730-record-architecture-decisions.md

@@ -0,0 +1,19 @@
+# Record architecture decisions
+
+Date: 2022-07-30
+
+## Status
+
+Accepted
+
+## Context
+
+We need to record the architectural decisions made on this project.
+
+## Decision
+
+We will use Architecture Decision Records, as [described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
+
+## Consequences
+
+See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools).

python_event_sourcery-0.5.3a3/docs/adr/20230903-explicit-init-arguments-for-sqlalchemy-s-models.md

@@ -0,0 +1,129 @@
+# Explicit __init__ arguments for SQLAlchemy's models
+
+Date: 2023-09-03
+
+## Status
+
+Draft
+
+## Context
+
+We aim for having full support regarding 
+
+## Possible solutions
+
+### Use native support for dataclasses in SQLAlchemy
+
+Starting from SQLAlchemy 2.0, there's a [native support for dataclasses](https://docs.sqlalchemy.org/en/20/changelog/whatsnew_20.html#native-support-for-dataclasses-mapped-as-orm-models).
+
+However, it's less seamless than one might initially imagine. It comes down to inheriting explicitly from another base class, namely `sqlalchemy.orm.MappedAsDataclass` and using it as a base for models:
+```python
+from sqlalchemy.orm import DeclarativeBase
+from sqlalchemy.orm import MappedAsDataclass
+
+class Base(MappedAsDataclass, DeclarativeBase):
+    """subclasses will be converted to dataclasses"""
+
+class User(Base):
+    __tablename__ = "user_account"
+
+    id: Mapped[intpk] = mapped_column(init=False)
+```
+
+As a result, `User` becomes a dataclass with attached SQLAlchemy's behaviour.
+
+In terms of risk, this may cause compatibility issues. As a reminder, Event Sourcery's models are declared as bare classes (notice lack of inheritance from `Base`):
+
+```python
+class Stream:
+    __tablename__ = "event_sourcery_streams"
+    __table_args__ = (
+        UniqueConstraint("uuid", "category"),
+        UniqueConstraint("name", "category"),
+    )
+
+    id = mapped_column(BigInteger().with_variant(Integer(), "sqlite"), primary_key=True)
+```
+
+The assumption is that someone setting up a project with SQLAlchemy will have their own `Base` class and models. The library will let them attach our models to their declarative base later using `event_sourcery_sqlalchemy.models.configure_models`, like:
+
+```python
+@as_declarative()
+class Base:
+    pass
+
+
+# initialize Event Sourcery models, so they can be handled by SQLAlchemy and e.g. alembic
+configure_models(Base)
+```
+
+The exception is raised in case `MappedAsDataclass` appears multiple time in model's MRO, for example:
+- let's say we have a base class for our models that inherits from `MappedAsDataclass`
+- someone has their own `Base` that also inherits from `MappedAsDataclass`
+
+```
+sqlalchemy.exc.InvalidRequestError: Class <class 'event_sourcery_sqlalchemy.models.Stream'> is already a dataclass; ensure that base classes / decorator styles of establishing dataclasses are not being mixed. This can happen if a class that inherits from 'MappedAsDataclass', even indirectly, is been mapped with '@registry.mapped_as_dataclass'
+```
+
+To reproduce, add `MappedAsDataclass` as a base to any model and use this snippet:
+
+```python
+from sqlalchemy import create_engine
+from sqlalchemy.orm import DeclarativeBase, MappedAsDataclass
+
+from event_sourcery_sqlalchemy.models import configure_models
+
+
+engine = create_engine(
+    "sqlite+pysqlite:///:memory:", echo=True, future=True
+)
+
+
+class Base(MappedAsDataclass, DeclarativeBase):
+    pass
+
+
+Base.metadata.create_all(bind=engine)
+
+
+# initialize Event Sourcery models, so they can be handled by SQLAlchemy and e.g. alembic
+configure_models(Base)
+```
+
+
+### Create base class for models with overridden __init__
+
+There is a recipe for providing base class model with overriding `__init__`:
+```python
+class ModelBase:
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        return super().__init__(*args, **kwargs)
+```
+
+This basically makes mypy unable to verify anything extra because such a signature allows everything to be passed in. Conversely, all operations are considered to be correct from type checker's perspective.
+
+This solution is a bit tricky and just gets rid of warnings, but doesn't give us any additional benefits.
+
+### Define our own, explicit `__init__` definition
+
+We can simply provide tailored `__init__` for each model to get type safety out of the box.
+
+```python
+class Stream:
+    def __init__(self) -> None:
+        pass
+
+
+```
+
+This is safe & compatible with other ORM's features because SQLAlchemy uses other means to build an object when e.g. fetching them from the database.
+In other words, SQLAlchemy internally is not invoking `__init__`.
+
+## Decision
+
+Writing custom `__init__` makes the most sense.
+
+## Consequences
+
+Whenever someone changes fields of a model (this should be rare after release), `__init__` needs to follow.
+However, this inconvenience can be potentially automated away in the future. At least, we could also have a custom static code check that would guard that.