python-event-sourcery 0.5.3a4__tar.gz → 0.5.3a5__tar.gz

{python_event_sourcery-0.5.3a4 → python_event_sourcery-0.5.3a5}/.github/workflows/main.yml

@@ -41,6 +41,12 @@ jobs:
           - 1113:1113
           - 2113:2113
 
+      rabbitmq:
+        image: rabbitmq:3.11.2
+        ports:
+          - '5672:5672'
+          - '15672:15672'
+
     steps:
     - uses: actions/checkout@v2
     - name: Install uv
@@ -48,11 +54,15 @@ jobs:
       with:
         python-version: ${{ matrix.python-version }}
         enable-cache: true
+    - name: Install poe
+      run: uv tool install poethepoet
     - name: Install deps
       run: uv sync --all-extras
     - name: Run linters
-      run: make lint
+      run: poe lint-fix
     - name: Build docs
       run: uv run --all-extras zensical build --clean
+    - name: Test docs code snippets
+      run: poe docs-test
     - name: Test with pytest
-      run: make test
+      run: poe test

{python_event_sourcery-0.5.3a4 → python_event_sourcery-0.5.3a5}/AGENTS.md

@@ -21,9 +21,10 @@ uv sync --all-extras   # install all deps (dev group is included by default)
 
 ```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
+poe test              # pytest with coverage (fail_under = 100)
+poe lint-fix              # ruff format + ruff check + mypy (must pass clean)
+poe docs-test         # pytest docs/code/ — snippets embedded in docs must pass
+poe 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`.
@@ -36,10 +37,12 @@ Run single tools via `uv run --all-extras <tool>`, e.g. `uv run --all-extras pyt
 
 ## Docs
 
-Changing public API or behavior may require updating `docs/` — pages embed runnable snippets from `docs/code/` (via `--8<--` includes). After touching docs code:
+Changing public API or behavior **requires** updating `docs/` and running docs tests —
+pages embed runnable snippets from `docs/code/` (via `--8<--` includes), and broken
+snippets go unnoticed without them. Docs tests need no docker services. 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
+poe docs-test                         # snippets are real tests, must pass (enforced in CI)
+poe docs-lint-fix                     # lint docs/code
 uv run --all-extras zensical build --clean   # verify docs build
 ```

python_event_sourcery-0.5.3a5/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Basics
+
+## Prerequisites
+
+- docker + docker compose / any compatible replacement
+- uv
+- [poe](https://poethepoet.natn.io/)
+
+## Installation
+
+```bash
+uv sync --all-extras
+```
+
+## Running tests
+
+```bash
+docker compose up
+poe test
+```
+
+## Running linters
+
+```bash
+poe lint-fix
+```
+
+# Documentation
+
+First, `cd docs/documentation`
+
+## Testing docs code snippets
+
+Snippets embedded in docs pages (`docs/documentation/`) are real tests living in
+`docs/code/`. They must pass — otherwise the docs silently show broken code.
+No docker services required (they run on in-memory/SQLite backends):
+
+```bash
+poe docs-test        # or: uv run --all-extras pytest docs/code/
+poe docs-lint-fix    # ruff format + check for docs/code/
+```
+
+Run them whenever you change public API, behavior, or anything in `docs/code/`.
+
+## Serve docs with live preview
+
+```bash
+poe docs-serve
+```
+
+## Deploy docs to github pages
+
+Docs get auto deployed from main after each change.
+

{python_event_sourcery-0.5.3a4 → python_event_sourcery-0.5.3a5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-event-sourcery
-Version: 0.5.3a4
+Version: 0.5.3a5
 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

{python_event_sourcery-0.5.3a4 → python_event_sourcery-0.5.3a5}/docs/code/test_get_started.py

@@ -14,10 +14,12 @@ def test_get_started():
         InvoicePaid(invoice_number="1003"),
         stream_id=StreamId(name="invoices/1003"),
     )
-
-    for recorded in event_store.load_stream(StreamId(name="invoices/1003")):
-        print(recorded.event, recorded.version)
     # --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

{python_event_sourcery-0.5.3a4 → python_event_sourcery-0.5.3a5}/docs/get_started.md

@@ -16,7 +16,7 @@ pip install "python-event-sourcery[sqlalchemy]"
 
 The example below uses the in-memory backend, so you can run it right away, without setting up a database.
 
-Define an event by inheriting from the [Event] base class, then append it to a stream and read it back:
+Define an event by inheriting from the [Event] base class, then append it to a stream:
 
 ```python
 --8<--
@@ -24,6 +24,16 @@ docs/code/test_get_started.py:get_started_01
 --8<--
 ```
 
+## Reading events
+
+Events from a given stream can be read back at once:
+
+```python
+--8<--
+docs/code/test_get_started.py:get_started_02
+--8<--
+```
+
 Output:
 
 ```

{python_event_sourcery-0.5.3a4 → python_event_sourcery-0.5.3a5}/docs/index.md

@@ -1,3 +1,7 @@
 # Python Event Sourcery
 
 A library for event-based systems in Python. For event sourcing, CQRS, and event-driven architectures.
+
+## What's first?
+
+- **[Get started guide](get_started.md)** - try out the library in 5 minutes

{python_event_sourcery-0.5.3a4 → python_event_sourcery-0.5.3a5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-event-sourcery"
-version = "0.5.3a4"
+version = "0.5.3a5"
 requires-python = ">=3.10"
 description = "A library for event-based systems in Python."
 readme = "README.md"
@@ -141,3 +141,83 @@ packages = [
     "event_sourcery_kurrentdb",
     "event_sourcery_sqlalchemy",
 ]
+
+[tool.poe.executor]
+type = "uv"
+extra = ["sqlalchemy", "kurrentdb", "django"]
+
+[tool.poe.env]
+SRC_DIRS = "./event_sourcery_sqlalchemy ./event_sourcery ./event_sourcery_django ./event_sourcery_kurrentdb"
+COV_ARGS = "--cov ./event_sourcery_sqlalchemy --cov ./event_sourcery --cov ./event_sourcery_django --cov ./event_sourcery_kurrentdb"
+
+[tool.poe.tasks.docs-test]
+cmd = "pytest docs/code/"
+
+[tool.poe.tasks.docs-lint-fix]
+shell = """
+    ruff format docs/code tests/
+    ruff check docs/code --fix
+"""
+
+[tool.poe.tasks.docs-serve]
+cmd = "zensical serve"
+
+[tool.poe.tasks.fmt]
+cmd = "ruff format ${SRC_DIRS} tests/"
+
+[tool.poe.tasks.lint]
+cmd = "ruff check ${SRC_DIRS} tests/ --fix"
+
+[tool.poe.tasks.typecheck]
+ref = "typecheck-py314"
+
+[tool.poe.tasks.typecheck-py314]
+cmd = "mypy ${SRC_DIRS} tests/"
+
+[tool.poe.tasks.typecheck-py313]
+cmd = "mypy ${SRC_DIRS} tests/"
+executor = {isolated = true, python = "3.13"}
+
+[tool.poe.tasks.typecheck-py312]
+cmd = "mypy ${SRC_DIRS} tests/"
+executor = {isolated = true, python = "3.12"}
+
+[tool.poe.tasks.typecheck-py311]
+cmd = "mypy ${SRC_DIRS} tests/"
+executor = {isolated = true, python = "3.11"}
+
+[tool.poe.tasks.typecheck-py310]
+cmd = "mypy ${SRC_DIRS} tests/"
+executor = {isolated = true, python = "3.10"}
+
+[tool.poe.tasks.lint-fix]
+sequence = ["fmt", "lint", "typecheck"]
+
+[tool.poe.tasks.test]
+ref = "test-py314"
+
+[tool.poe.tasks.test-py314]
+cmd = "pytest ${COV_ARGS} tests/"
+
+[tool.poe.tasks.test-py313]
+cmd = "pytest ${COV_ARGS} tests/"
+executor = {isolated = true, python = "3.13"}
+
+[tool.poe.tasks.test-py312]
+cmd = "pytest ${COV_ARGS} tests/"
+executor = {isolated = true, python = "3.12"}
+
+[tool.poe.tasks.test-py311]
+cmd = "pytest ${COV_ARGS} tests/"
+executor = {isolated = true, python = "3.11"}
+
+[tool.poe.tasks.test-py310]
+cmd = "pytest ${COV_ARGS} tests/"
+executor = {isolated = true, python = "3.10"}
+
+[tool.poe.tasks.test-all]
+sequence = ["test-py314", "test-py313", "test-py312", "test-py311", "test-py310"]
+
+[tool.poe.tasks.typecheck-all]
+sequence = ["typecheck-py314", "typecheck-py313", "typecheck-py312", "typecheck-py311", "typecheck-py310"]
+

{python_event_sourcery-0.5.3a4 → python_event_sourcery-0.5.3a5}/uv.lock

@@ -1221,7 +1221,7 @@ wheels = [
 
 [[package]]
 name = "python-event-sourcery"
-version = "0.5.3a4"
+version = "0.5.3a5"
 source = { editable = "." }
 dependencies = [
     { name = "more-itertools" },

{python_event_sourcery-0.5.3a4 → python_event_sourcery-0.5.3a5}/zensical.toml

@@ -5,9 +5,7 @@ repo_name = "python-event-sourcery/python-event-sourcery"
 nav = [
   { "Event Sourcery" = "index.md" },
   { "Get Started" = "get_started.md" },
-  { "Concepts" = [
-    { "Basics" = "concepts/basics.md" },
-  ] },
+  { "Concepts" = "concepts.md" },
   { "Recipes" = [
     { "Defining events" = "recipes/defining_events.md" },
     { "Integrate with your app" = "recipes/integrate.md" },

python_event_sourcery-0.5.3a4/CONTRIBUTING.md

@@ -1,40 +0,0 @@
-# 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.3a4/Makefile

@@ -1,20 +0,0 @@
-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