Merge branch 'main' into claude/issue-48-20251027-0100

Author: strawgate

.github/workflows/claude-on-mention.yml

@@ -27,6 +27,11 @@ jobs:
         with:
           fetch-depth: 1
 
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
       # Install UV package manager
       - name: Install UV
         uses: astral-sh/setup-uv@v7

.github/workflows/claude-on-open-label.yml

@@ -22,6 +22,11 @@ jobs:
         with:
           fetch-depth: 1
 
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
       # Install UV package manager
       - name: Install UV
         uses: astral-sh/setup-uv@v7

.github/workflows/docs.yml

@@ -0,0 +1,35 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install documentation dependencies
+        run: uv pip install --system mkdocs mkdocs-material 'mkdocstrings[python]' mkdocstrings-python
+
+      - name: Build documentation
+        run: mkdocs build
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

.github/workflows/test.yml

@@ -30,6 +30,52 @@ jobs:
           config: '.markdownlint.jsonc'
           globs: '**/*.md'
 
+  codegen_check:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: "Install uv"
+        uses: astral-sh/setup-uv@v6
+
+      - name: "Set up Python 3.10"
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: "Install Node.js"
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: "Install dependencies"
+        run: make sync
+
+      - name: "Run codegen"
+        run: make codegen
+
+      - name: "Run lint"
+        run: make lint
+
+      - name: "Check for uncommitted changes"
+        run: |
+          if ! git diff --exit-code; then
+            echo "Error: Modified files detected after running 'make codegen lint'."
+            echo "Please run 'make codegen lint' locally and commit the changes."
+            exit 1
+          fi
+          if [ -n "$(git ls-files --others --exclude-standard)" ]; then
+            echo "Error: Untracked files detected after running 'make codegen lint'."
+            echo "Untracked files:"
+            git ls-files --others --exclude-standard
+            echo "Please run 'make codegen lint' locally and commit the changes."
+            exit 1
+          fi
+
   static_analysis:
     runs-on: ubuntu-latest
 
@@ -66,6 +112,7 @@ jobs:
   test_quick:
     needs:
       - markdown_lint
+      - codegen_check
       - static_analysis
     timeout-minutes: 10
     strategy:

.markdownlint.jsonc

@@ -5,5 +5,8 @@
     "line_length": 80,
     "code_blocks": false, // Don't restrict line length in code blocks
     "tables": false // Don't restrict line length in tables
+  },
+  "MD024": {
+    "siblings_only": true // Allow duplicate headings in different sections
   }
 }

AGENTS.md

@@ -216,6 +216,11 @@ make sync
 GitHub Actions workflows are in `.github/workflows/`:
 
 - `test.yml` - Run tests across packages
+  - `codegen_check` job - Ensures `make codegen lint` has been run before
+    commits
+  - `static_analysis` job - Runs linting and type checking per package
+  - `test_quick` and `test_all` jobs - Run tests across Python versions and
+    platforms
 - `publish.yml` - Publish packages to PyPI
 - `claude-on-mention.yml` - Claude Code assistant (can make PRs)
 - `claude-on-open-label.yml` - Claude triage assistant (read-only analysis)

DEVELOPING.md

@@ -100,6 +100,11 @@ make precommit
 
 This runs linting, type checking, and code generation.
 
+**Important**: CI will fail if `make codegen lint` has not been run before
+committing. The `codegen_check` job in the test workflow verifies that
+running these commands produces no file changes, ensuring all generated
+code and formatting is up to date.
+
 ## Using Makefile in CI
 
 The Makefile targets support per-project operations, making them

Makefile

@@ -1,5 +1,5 @@
 .PHONY: bump-version bump-version-dry codegen lint typecheck sync precommit test build help
-.PHONY: install test-aio test-sync test-shared
+.PHONY: install test-aio test-sync test-shared docs-serve docs-build docs-deploy
 
 # Default target - show help
 .DEFAULT_GOAL := help
@@ -19,6 +19,9 @@ help:
 	@echo "  make build             - Build all packages"
 	@echo "  make codegen           - Generate sync package from async"
 	@echo "  make precommit         - Run pre-commit checks (lint + typecheck + codegen)"
+	@echo "  make docs-serve        - Start documentation server"
+	@echo "  make docs-build        - Build documentation"
+	@echo "  make docs-deploy       - Deploy documentation to GitHub Pages"
 	@echo ""
 	@echo "Per-project targets (use PROJECT=<path>):"
 	@echo "  make sync PROJECT=key-value/key-value-aio"
@@ -119,4 +122,17 @@ else
 	@cd key-value/key-value-shared && uv build .
 endif
 
-precommit: lint codegen lint typecheck 
+precommit: lint codegen lint typecheck
+
+# Documentation targets
+docs-serve:
+	@echo "Starting documentation server..."
+	@uv run --extra docs mkdocs serve
+
+docs-build:
+	@echo "Building documentation..."
+	@uv run --extra docs mkdocs build
+
+docs-deploy:
+	@echo "Deploying documentation to GitHub Pages..."
+	@uv run --extra docs mkdocs gh-deploy --force

README.md

@@ -6,6 +6,14 @@ This monorepo contains two libraries:
 - `py-key-value-sync`: Sync key-value store library (under development;
   generated from the async API).
 
+## Documentation
+
+- [Full Documentation](https://strawgate.github.io/py-key-value/)
+- [Getting Started Guide](https://strawgate.github.io/py-key-value/getting-started/)
+- [Wrappers Guide](https://strawgate.github.io/py-key-value/wrappers/)
+- [Adapters Guide](https://strawgate.github.io/py-key-value/adapters/)
+- [API Reference](https://strawgate.github.io/py-key-value/api/protocols/)
+
 ## Why use this library?
 
 - **Multiple backends**: DynamoDB, Elasticsearch, Memcached, MongoDB,
@@ -246,6 +254,7 @@ the protocol, your application code might be simplified by using an adapter.
 
 | Adapter | Description | Example |
 |---------|:------------|:------------------|
+| DataclassAdapter | Type-safe storage/retrieval of dataclass models with transparent serialization/deserialization. | `DataclassAdapter(key_value=memory_store, dataclass_type=User)` |
 | PydanticAdapter | Type-safe storage/retrieval of Pydantic models with transparent serialization/deserialization. | `PydanticAdapter(key_value=memory_store, pydantic_model=User)` |
 | RaiseOnMissingAdapter | Optional raise-on-missing behavior for `get`, `get_many`, `ttl`, and `ttl_many`. | `RaiseOnMissingAdapter(key_value=memory_store)` |