red-queen 0.1.1__tar.gz

red_queen-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+
+  ty:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --dev
+      - run: uv run ty check src/
+
+  pytest:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --dev --python ${{ matrix.python-version }}
+      - run: uv run --python ${{ matrix.python-version }} pytest

red_queen-0.1.1/.github/workflows/conventional-commits.yml

@@ -0,0 +1,15 @@
+name: Conventional Commits
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  conventional-commits:
+    if: ${{ !startsWith(github.head_ref, 'release-please--') }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: webiny/action-conventional-commits@v1.3.0

red_queen-0.1.1/.github/workflows/release-please.yml

@@ -0,0 +1,40 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+  id-token: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  publish:
+    needs: release-please
+    if: needs.release-please.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/red-queen
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

red_queen-0.1.1/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/

red_queen-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check --fix
+        language: system
+        types: [python]
+
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format
+        language: system
+        types: [python]
+
+      - id: ty
+        name: ty check
+        entry: uv run ty check src/
+        language: system
+        pass_filenames: false
+        files: ^src/

red_queen-0.1.1/.python-version

@@ -0,0 +1 @@
+3.13

red_queen-0.1.1/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.1"
+}

red_queen-0.1.1/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.1.1](https://github.com/mahdilamb/red-queen/compare/red-queen-v0.1.0...red-queen-v0.1.1) (2026-04-12)
+
+
+### Features
+
+* initial release of red-queen ([2c69149](https://github.com/mahdilamb/red-queen/commit/2c691498b342112aed5f7af48e8cce83cee3b587))

red_queen-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mahdi Lamb
+
+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.

red_queen-0.1.1/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: red-queen
+Version: 0.1.1
+Summary: Redis schema migration tool with Pydantic model tracking
+Author-email: Mahdi Lamb <mahdilamb@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: redis>=7.4.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# red-queen
+
+Schema migration tool for Redis-backed Pydantic models. Track model changes, generate versioned migration scripts, and apply them using async SCAN-based key iteration.
+
+## Installation
+
+```toml
+# pyproject.toml
+dependencies = ["red-queen"]
+```
+
+## Quick start
+
+### 1. Decorate your models
+
+```python
+from pydantic import BaseModel, Field, RootModel
+from red_queen import red_queen, migrates_from
+from typing import Annotated
+
+@red_queen(key="user:{user_id}:profile:")
+class UserProfile(BaseModel):
+    name: str
+    email: str
+
+@red_queen(key="agent:session:{session_id}:display")
+class DisplayMessages(RootModel[list[DisplayMessage]]):
+    """Stored as a JSON array."""
+
+# Field renames
+@red_queen(key="item:{item_id}")
+class Item(BaseModel):
+    title: Annotated[str, migrates_from("name")]  # explicit rename
+    label: Annotated[str, Field(alias="old_label")]  # alias-based rename
+```
+
+Key patterns use f-string style placeholders. `match` is auto-derived by replacing `{...}` with `*` for SCAN.
+
+### 2. Configure in pyproject.toml
+
+```toml
+[tool.red-queen]
+migrations_dir = "migrations"
+deletion_protection = false  # or true, or an integer (TTL in seconds)
+
+[tool.red-queen.profiles.default]
+default = true
+host = "localhost"     # defaults to localhost
+port = 6379            # defaults to 6379
+db = 0                 # defaults to 0
+migrations_collection = "my_collection"
+model_search_path = ["myapp.models"]
+```
+
+`host`, `port`, and `db` default to `localhost`, `6379`, and `0`. All string values support `$ENV_VAR` expansion.
+
+**Profile resolution order:** `--profile` CLI flag > `RED_QUEEN_PROFILE` env var > profile with `default = true`.
+
+Multiple profiles (e.g. local + docker):
+
+```toml
+[tool.red-queen.profiles.default]
+default = true
+migrations_collection = "agent"
+model_search_path = ["agent.types"]
+
+[tool.red-queen.profiles.docker]
+host = "redis"
+migrations_collection = "agent"
+model_search_path = ["agent.types"]
+```
+
+### 3. Generate and apply migrations
+
+```bash
+# Create the initial schema snapshot
+red-queen revision -m "initial"
+
+# Show current state
+red-queen show
+
+# After changing models, generate a new revision
+red-queen revision -m "add email field"
+
+# Check if there are pending changes (exit 1 if none, useful in CI)
+red-queen revision --check
+
+# Show what changed
+red-queen diff
+
+# Apply pending migrations (stages first, prompts for confirmation)
+red-queen up
+
+# Apply without confirmation
+red-queen up --auto-apply
+
+# Downgrade to a specific revision
+red-queen down 0001
+red-queen down --root  # revert all
+
+# Reset to a specific revision (up or down as needed)
+red-queen reset 0002
+red-queen reset --root
+```
+
+All mutation commands (`up`, `down`, `reset`) support `--auto-apply` to skip the staging confirmation prompt.
+
+## Model discovery
+
+`model_search_path` accepts:
+
+- **Directories:** `"src/myapp/models"` -- walks all `.py` files
+- **Single files:** `"src/myapp/models.py"`
+- **Dotted module paths:** `"myapp.models"` -- imports the module and recursively walks all submodules
+
+## Schema tracking
+
+Snapshots use `model_json_schema()`, which captures the full recursive schema including nested models. A change to any nested model triggers a new revision.
+
+## Generated migrations
+
+Revisions auto-generate `upgrade` and `downgrade` functions:
+
+- **Field added with default** -- sets the default value
+- **Field added, optional (factory)** -- infers zero-value from type (`[]`, `{}`, `""`, `0`, etc.)
+- **Field added, required, no default** -- `# TODO` comment
+- **Field removed** -- backs up values, deletes from data
+
+## Deletion protection
+
+Controls what happens when fields are removed:
+
+```toml
+[tool.red-queen]
+deletion_protection = false  # backup without TTL (default)
+deletion_protection = true   # generate TODO, don't delete
+deletion_protection = 3600   # backup with 1-hour TTL
+```
+
+When using an integer TTL, backups expire after the specified seconds. If a downgrade runs after the TTL, a warning is emitted for each key where the backup has expired and fields cannot be restored.
+
+## Python API
+
+```python
+from red_queen import (
+    red_queen,
+    migrates_from,
+    auto_migrate_up,
+    migrate_up,
+    migrate_down,
+    apply_plan,
+    find_one,
+    get_one,
+)
+```
+
+### Auto-migrate on startup
+
+```python
+from red_queen import auto_migrate_up
+
+# Resolves config, connects to Redis, applies all pending migrations.
+# Uses RED_QUEEN_PROFILE env var or default profile.
+await auto_migrate_up()
+```
+
+### FastAPI lifespan example
+
+```python
+from red_queen import auto_migrate_up
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await auto_migrate_up()
+    yield
+```
+
+### Query utilities
+
+```python
+# find_one: format key pattern with args/kwargs, then GET
+profile = await find_one(UserProfile, "123")
+profile = await find_one(UserProfile, user_id="123")
+raw = await find_one(UserProfile, "123", return_raw=True)
+
+# get_one: GET by full literal key
+profile = await get_one(UserProfile, "user:123:profile:")
+raw = await get_one(UserProfile, "user:123:profile:", return_raw=True)
+```
+
+### Low-level API
+
+For full control, use `migrate_up` / `migrate_down` directly with an explicit Redis client, migrations dir, and model list. See the CLI command implementations for examples.

red_queen-0.1.1/README.md

@@ -0,0 +1,193 @@
+# red-queen
+
+Schema migration tool for Redis-backed Pydantic models. Track model changes, generate versioned migration scripts, and apply them using async SCAN-based key iteration.
+
+## Installation
+
+```toml
+# pyproject.toml
+dependencies = ["red-queen"]
+```
+
+## Quick start
+
+### 1. Decorate your models
+
+```python
+from pydantic import BaseModel, Field, RootModel
+from red_queen import red_queen, migrates_from
+from typing import Annotated
+
+@red_queen(key="user:{user_id}:profile:")
+class UserProfile(BaseModel):
+    name: str
+    email: str
+
+@red_queen(key="agent:session:{session_id}:display")
+class DisplayMessages(RootModel[list[DisplayMessage]]):
+    """Stored as a JSON array."""
+
+# Field renames
+@red_queen(key="item:{item_id}")
+class Item(BaseModel):
+    title: Annotated[str, migrates_from("name")]  # explicit rename
+    label: Annotated[str, Field(alias="old_label")]  # alias-based rename
+```
+
+Key patterns use f-string style placeholders. `match` is auto-derived by replacing `{...}` with `*` for SCAN.
+
+### 2. Configure in pyproject.toml
+
+```toml
+[tool.red-queen]
+migrations_dir = "migrations"
+deletion_protection = false  # or true, or an integer (TTL in seconds)
+
+[tool.red-queen.profiles.default]
+default = true
+host = "localhost"     # defaults to localhost
+port = 6379            # defaults to 6379
+db = 0                 # defaults to 0
+migrations_collection = "my_collection"
+model_search_path = ["myapp.models"]
+```
+
+`host`, `port`, and `db` default to `localhost`, `6379`, and `0`. All string values support `$ENV_VAR` expansion.
+
+**Profile resolution order:** `--profile` CLI flag > `RED_QUEEN_PROFILE` env var > profile with `default = true`.
+
+Multiple profiles (e.g. local + docker):
+
+```toml
+[tool.red-queen.profiles.default]
+default = true
+migrations_collection = "agent"
+model_search_path = ["agent.types"]
+
+[tool.red-queen.profiles.docker]
+host = "redis"
+migrations_collection = "agent"
+model_search_path = ["agent.types"]
+```
+
+### 3. Generate and apply migrations
+
+```bash
+# Create the initial schema snapshot
+red-queen revision -m "initial"
+
+# Show current state
+red-queen show
+
+# After changing models, generate a new revision
+red-queen revision -m "add email field"
+
+# Check if there are pending changes (exit 1 if none, useful in CI)
+red-queen revision --check
+
+# Show what changed
+red-queen diff
+
+# Apply pending migrations (stages first, prompts for confirmation)
+red-queen up
+
+# Apply without confirmation
+red-queen up --auto-apply
+
+# Downgrade to a specific revision
+red-queen down 0001
+red-queen down --root  # revert all
+
+# Reset to a specific revision (up or down as needed)
+red-queen reset 0002
+red-queen reset --root
+```
+
+All mutation commands (`up`, `down`, `reset`) support `--auto-apply` to skip the staging confirmation prompt.
+
+## Model discovery
+
+`model_search_path` accepts:
+
+- **Directories:** `"src/myapp/models"` -- walks all `.py` files
+- **Single files:** `"src/myapp/models.py"`
+- **Dotted module paths:** `"myapp.models"` -- imports the module and recursively walks all submodules
+
+## Schema tracking
+
+Snapshots use `model_json_schema()`, which captures the full recursive schema including nested models. A change to any nested model triggers a new revision.
+
+## Generated migrations
+
+Revisions auto-generate `upgrade` and `downgrade` functions:
+
+- **Field added with default** -- sets the default value
+- **Field added, optional (factory)** -- infers zero-value from type (`[]`, `{}`, `""`, `0`, etc.)
+- **Field added, required, no default** -- `# TODO` comment
+- **Field removed** -- backs up values, deletes from data
+
+## Deletion protection
+
+Controls what happens when fields are removed:
+
+```toml
+[tool.red-queen]
+deletion_protection = false  # backup without TTL (default)
+deletion_protection = true   # generate TODO, don't delete
+deletion_protection = 3600   # backup with 1-hour TTL
+```
+
+When using an integer TTL, backups expire after the specified seconds. If a downgrade runs after the TTL, a warning is emitted for each key where the backup has expired and fields cannot be restored.
+
+## Python API
+
+```python
+from red_queen import (
+    red_queen,
+    migrates_from,
+    auto_migrate_up,
+    migrate_up,
+    migrate_down,
+    apply_plan,
+    find_one,
+    get_one,
+)
+```
+
+### Auto-migrate on startup
+
+```python
+from red_queen import auto_migrate_up
+
+# Resolves config, connects to Redis, applies all pending migrations.
+# Uses RED_QUEEN_PROFILE env var or default profile.
+await auto_migrate_up()
+```
+
+### FastAPI lifespan example
+
+```python
+from red_queen import auto_migrate_up
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await auto_migrate_up()
+    yield
+```
+
+### Query utilities
+
+```python
+# find_one: format key pattern with args/kwargs, then GET
+profile = await find_one(UserProfile, "123")
+profile = await find_one(UserProfile, user_id="123")
+raw = await find_one(UserProfile, "123", return_raw=True)
+
+# get_one: GET by full literal key
+profile = await get_one(UserProfile, "user:123:profile:")
+raw = await get_one(UserProfile, "user:123:profile:", return_raw=True)
+```
+
+### Low-level API
+
+For full control, use `migrate_up` / `migrate_down` directly with an explicit Redis client, migrations dir, and model list. See the CLI command implementations for examples.

red_queen-0.1.1/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "red-queen"
+version = "0.1.1"
+description = "Redis schema migration tool with Pydantic model tracking"
+readme = "README.md"
+authors = [
+    { name = "Mahdi Lamb", email = "mahdilamb@gmail.com" }
+]
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+    "click>=8.1.0",
+    "pydantic>=2.0.0",
+    "redis>=7.4.0",
+    "tomli>=2.0.0; python_version < '3.11'",
+]
+
+[project.scripts]
+red-queen = "red_queen.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+target-version = "py310"
+extend-exclude = ["**/migrations"]
+
+[tool.ruff.lint]
+select = [
+    "E",     # pycodestyle errors
+    "W",     # pycodestyle warnings
+    "F",     # pyflakes
+    "I",     # isort
+    "N",     # pep8-naming
+    "UP",    # pyupgrade
+    "B",     # flake8-bugbear
+    "SIM",   # flake8-simplify
+    "TCH",   # flake8-type-checking
+    "RUF",   # ruff-specific rules
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["red_queen"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "--import-mode=importlib"
+
+[dependency-groups]
+dev = [
+    "fakeredis>=2.35.0",
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.3.0",
+    "ruff>=0.15.10",
+    "ty>=0.0.29",
+]

red_queen-0.1.1/release-please-config.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "packages": {
+    ".": {
+      "release-type": "python",
+      "package-name": "red-queen",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": true,
+      "extra-files": [
+        {
+          "type": "toml",
+          "path": "uv.lock",
+          "jsonpath": "$.package[?(@.name=='red-queen')].version"
+        }
+      ]
+    }
+  }
+}

red_queen-0.1.1/src/red_queen/__init__.py

@@ -0,0 +1,31 @@
+"""Redis migration tool with Pydantic model tracking."""
+
+from red_queen._config import load_config, resolve_profile
+from red_queen._decorator import (
+    get_registered_model,
+    get_registry,
+    migrates_from,
+    red_queen,
+)
+from red_queen._migration import (
+    apply_plan,
+    auto_migrate_up,
+    migrate_down,
+    migrate_up,
+)
+from red_queen._util import find_one, get_one
+
+__all__ = [
+    "apply_plan",
+    "auto_migrate_up",
+    "find_one",
+    "get_one",
+    "get_registered_model",
+    "get_registry",
+    "load_config",
+    "migrate_down",
+    "migrate_up",
+    "migrates_from",
+    "red_queen",
+    "resolve_profile",
+]

red_queen-0.1.1/src/red_queen/__main__.py

@@ -0,0 +1,11 @@
+"""CLI entry point for red-queen."""
+
+from red_queen.commands import cli
+
+
+def main() -> None:
+    cli()
+
+
+if __name__ == "__main__":
+    main()