redis-queen 0.2.0__tar.gz

redis_queen-0.2.0/.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", "3.14"]
+    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

redis_queen-0.2.0/.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

redis_queen-0.2.0/.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/redis-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

redis_queen-0.2.0/.gitignore

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

redis_queen-0.2.0/.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/

redis_queen-0.2.0/.python-version

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

redis_queen-0.2.0/.release-please-manifest.json

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

redis_queen-0.2.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+## [0.2.0](https://github.com/mahdilamb/redis-queen/compare/redis-queen-v0.1.2...redis-queen-v0.2.0) (2026-04-12)
+
+
+### ⚠ BREAKING CHANGES
+
+* Package name, import module, CLI command, config section, and environment variable have all been renamed.
+
+### Features
+
+* initial release of red-queen ([2c69149](https://github.com/mahdilamb/redis-queen/commit/2c691498b342112aed5f7af48e8cce83cee3b587))
+
+
+### Documentation
+
+* add badges to README ([5c2d6d4](https://github.com/mahdilamb/redis-queen/commit/5c2d6d4dcd0f350f359d4f32085d626b8df13c34))
+* add badges, classifiers, and 3.14 to CI matrix ([0b5b397](https://github.com/mahdilamb/redis-queen/commit/0b5b39786ee459576a231232639127f755fcabd0))
+* remove alias-as-rename example from README ([2d3ac74](https://github.com/mahdilamb/redis-queen/commit/2d3ac74838922cb4d74d5026cfd7273796e8315d))
+* remove alias-as-rename example from README ([5b5ecc3](https://github.com/mahdilamb/redis-queen/commit/5b5ecc38d5e40f492924a9cace1315d7fb066b30))
+
+
+### Code Refactoring
+
+* rename package from red-queen to redis-queen ([13532d6](https://github.com/mahdilamb/redis-queen/commit/13532d6b6be956f643d5dc4ec1f92f98f3f19019))
+
+## [0.1.2](https://github.com/mahdilamb/redis-queen/compare/redis-queen-v0.1.1...redis-queen-v0.1.2) (2026-04-12)
+
+
+### Documentation
+
+* add badges to README ([5c2d6d4](https://github.com/mahdilamb/redis-queen/commit/5c2d6d4dcd0f350f359d4f32085d626b8df13c34))
+* add badges, classifiers, and 3.14 to CI matrix ([0b5b397](https://github.com/mahdilamb/redis-queen/commit/0b5b39786ee459576a231232639127f755fcabd0))
+* remove alias-as-rename example from README ([2d3ac74](https://github.com/mahdilamb/redis-queen/commit/2d3ac74838922cb4d74d5026cfd7273796e8315d))
+* remove alias-as-rename example from README ([5b5ecc3](https://github.com/mahdilamb/redis-queen/commit/5b5ecc38d5e40f492924a9cace1315d7fb066b30))
+
+## [0.1.1](https://github.com/mahdilamb/redis-queen/compare/redis-queen-v0.1.0...redis-queen-v0.1.1) (2026-04-12)
+
+
+### Features
+
+* initial release of redis-queen ([2c69149](https://github.com/mahdilamb/redis-queen/commit/2c691498b342112aed5f7af48e8cce83cee3b587))

redis_queen-0.2.0/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.

redis_queen-0.2.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: redis-queen
+Version: 0.2.0
+Summary: Redis schema migration tool with Pydantic model tracking
+Author-email: Mahdi Lamb <mahdilamb@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+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
+
+# redis-queen
+
+[![CI](https://github.com/mahdilamb/redis-queen/actions/workflows/ci.yml/badge.svg)](https://github.com/mahdilamb/redis-queen/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/redis-queen)](https://pypi.org/project/redis-queen/)
+[![Python](https://img.shields.io/pypi/pyversions/redis-queen)](https://pypi.org/project/redis-queen/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+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 = ["redis-queen"]
+```
+
+## Quick start
+
+### 1. Decorate your models
+
+```python
+from pydantic import BaseModel, Field, RootModel
+from redis_queen import redis_queen, migrates_from
+from typing import Annotated
+
+@redis_queen(key="user:{user_id}:profile:")
+class UserProfile(BaseModel):
+    name: str
+    email: str
+
+@redis_queen(key="agent:session:{session_id}:display")
+class DisplayMessages(RootModel[list[DisplayMessage]]):
+    """Stored as a JSON array."""
+
+# Field renames
+@redis_queen(key="item:{item_id}")
+class Item(BaseModel):
+    title: Annotated[str, migrates_from("name")]  # tracks rename from "name"
+```
+
+Key patterns use f-string style placeholders. `match` is auto-derived by replacing `{...}` with `*` for SCAN.
+
+### 2. Configure in pyproject.toml
+
+```toml
+[tool.redis-queen]
+migrations_dir = "migrations"
+deletion_protection = false  # or true, or an integer (TTL in seconds)
+
+[tool.redis-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 > `REDIS_QUEEN_PROFILE` env var > profile with `default = true`.
+
+Multiple profiles (e.g. local + docker):
+
+```toml
+[tool.redis-queen.profiles.default]
+default = true
+migrations_collection = "agent"
+model_search_path = ["agent.types"]
+
+[tool.redis-queen.profiles.docker]
+host = "redis"
+migrations_collection = "agent"
+model_search_path = ["agent.types"]
+```
+
+### 3. Generate and apply migrations
+
+```bash
+# Create the initial schema snapshot
+redis-queen revision -m "initial"
+
+# Show current state
+redis-queen show
+
+# After changing models, generate a new revision
+redis-queen revision -m "add email field"
+
+# Check if there are pending changes (exit 1 if none, useful in CI)
+redis-queen revision --check
+
+# Show what changed
+redis-queen diff
+
+# Apply pending migrations (stages first, prompts for confirmation)
+redis-queen up
+
+# Apply without confirmation
+redis-queen up --auto-apply
+
+# Downgrade to a specific revision
+redis-queen down 0001
+redis-queen down --root  # revert all
+
+# Reset to a specific revision (up or down as needed)
+redis-queen reset 0002
+redis-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.redis-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 redis_queen import (
+    redis_queen,
+    migrates_from,
+    auto_migrate_up,
+    migrate_up,
+    migrate_down,
+    apply_plan,
+    find_one,
+    get_one,
+)
+```
+
+### Auto-migrate on startup
+
+```python
+from redis_queen import auto_migrate_up
+
+# Resolves config, connects to Redis, applies all pending migrations.
+# Uses REDIS_QUEEN_PROFILE env var or default profile.
+await auto_migrate_up()
+```
+
+### FastAPI lifespan example
+
+```python
+from redis_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.

redis_queen-0.2.0/README.md

@@ -0,0 +1,197 @@
+# redis-queen
+
+[![CI](https://github.com/mahdilamb/redis-queen/actions/workflows/ci.yml/badge.svg)](https://github.com/mahdilamb/redis-queen/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/redis-queen)](https://pypi.org/project/redis-queen/)
+[![Python](https://img.shields.io/pypi/pyversions/redis-queen)](https://pypi.org/project/redis-queen/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+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 = ["redis-queen"]
+```
+
+## Quick start
+
+### 1. Decorate your models
+
+```python
+from pydantic import BaseModel, Field, RootModel
+from redis_queen import redis_queen, migrates_from
+from typing import Annotated
+
+@redis_queen(key="user:{user_id}:profile:")
+class UserProfile(BaseModel):
+    name: str
+    email: str
+
+@redis_queen(key="agent:session:{session_id}:display")
+class DisplayMessages(RootModel[list[DisplayMessage]]):
+    """Stored as a JSON array."""
+
+# Field renames
+@redis_queen(key="item:{item_id}")
+class Item(BaseModel):
+    title: Annotated[str, migrates_from("name")]  # tracks rename from "name"
+```
+
+Key patterns use f-string style placeholders. `match` is auto-derived by replacing `{...}` with `*` for SCAN.
+
+### 2. Configure in pyproject.toml
+
+```toml
+[tool.redis-queen]
+migrations_dir = "migrations"
+deletion_protection = false  # or true, or an integer (TTL in seconds)
+
+[tool.redis-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 > `REDIS_QUEEN_PROFILE` env var > profile with `default = true`.
+
+Multiple profiles (e.g. local + docker):
+
+```toml
+[tool.redis-queen.profiles.default]
+default = true
+migrations_collection = "agent"
+model_search_path = ["agent.types"]
+
+[tool.redis-queen.profiles.docker]
+host = "redis"
+migrations_collection = "agent"
+model_search_path = ["agent.types"]
+```
+
+### 3. Generate and apply migrations
+
+```bash
+# Create the initial schema snapshot
+redis-queen revision -m "initial"
+
+# Show current state
+redis-queen show
+
+# After changing models, generate a new revision
+redis-queen revision -m "add email field"
+
+# Check if there are pending changes (exit 1 if none, useful in CI)
+redis-queen revision --check
+
+# Show what changed
+redis-queen diff
+
+# Apply pending migrations (stages first, prompts for confirmation)
+redis-queen up
+
+# Apply without confirmation
+redis-queen up --auto-apply
+
+# Downgrade to a specific revision
+redis-queen down 0001
+redis-queen down --root  # revert all
+
+# Reset to a specific revision (up or down as needed)
+redis-queen reset 0002
+redis-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.redis-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 redis_queen import (
+    redis_queen,
+    migrates_from,
+    auto_migrate_up,
+    migrate_up,
+    migrate_down,
+    apply_plan,
+    find_one,
+    get_one,
+)
+```
+
+### Auto-migrate on startup
+
+```python
+from redis_queen import auto_migrate_up
+
+# Resolves config, connects to Redis, applies all pending migrations.
+# Uses REDIS_QUEEN_PROFILE env var or default profile.
+await auto_migrate_up()
+```
+
+### FastAPI lifespan example
+
+```python
+from redis_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.

redis_queen-0.2.0/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "redis-queen"
+version = "0.2.0"
+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"
+classifiers = [
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "click>=8.1.0",
+    "pydantic>=2.0.0",
+    "redis>=7.4.0",
+    "tomli>=2.0.0; python_version < '3.11'",
+]
+
+[project.scripts]
+redis-queen = "redis_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 = ["redis_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",
+]