pyverge

Schema evolution and migrations for versioned data models. Version your models, define migrations between versions, and converge payloads to a target schema at runtime.

The engine is provider-agnostic: it works on plain dicts and only touches a model library through the ModelAdapter seam. Pydantic and JSON Schema adapters ship today; adapters for other providers (dataclasses, attrs, marshmallow, MessagePack, etc.) plug in the same way.

Installation

# Core library (versioned registry, migration engine, diffing)
pip install git+https://github.com/JoHa-HQ/pyverge.git

# With CLI (init, validate, migrate, diff, export commands)
pip install "git+https://github.com/JoHa-HQ/pyverge.git#egg=pyverge[cli]"

Development dependencies are managed as a dependency group; install them with uv sync --group dev (or hatch/your tool's equivalent).

Quick Start

from typing import Literal

import semver
from pydantic import BaseModel

from pyverge.migration import (
    MigrationSettings,
    ModelManager,
    PydanticModelAdapter,
)

# A manager binds a version strategy to an adapter and settings.
UserManager = ModelManager[semver.Version].scoped(
    PydanticModelAdapter(),
    settings=MigrationSettings(),
)


# Register versioned models. Version and kind are read from the class itself.
@UserManager.model()
class UserV1(BaseModel):
    kind: Literal["User"] = "User"
    version: Literal["1.0.0"] = "1.0.0"
    name: str
    email: str


@UserManager.model()
class UserV2(BaseModel):
    kind: Literal["User"] = "User"
    version: Literal["2.0.0"] = "2.0.0"
    name: str
    email: str
    age: int | None = None


# Register a migration between two versions.
@UserManager.migration("User", "1.0.0", "2.0.0")
def add_age(data: dict) -> dict:
    return {**data, "age": None}


manager = UserManager()

# Migrate data — converges every versioned entry to the configured target.
migrated = manager.migrate(
    {"kind": "User", "version": "1.0.0", "name": "Alice", "email": "a@b.com"}
)
# -> {"kind": "User", "version": "2.0.0", "name": "Alice", "email": "a@b.com", "age": None}

CLI

# Requires: pip install "pyverge[cli]"

pyverge init          # Bootstrap a new project
pyverge validate      # Validate data against a schema version
pyverge migrate       # Migrate data between versions
pyverge diff          # Show differences between versions
pyverge export        # Export JSON Schema definitions
pyverge info          # List registered models and versions
pyverge managers      # List available managers from configuration

Configuration lives in a pyverge.toml (or [tool.pyverge] in pyproject.toml), pointing at the module that defines your manager.

# pyverge.toml
[managers]
user = "myapp.models:UserManager"

pyverge info          # List registered models and versions
pyverge validate data.json --manager user --version 1.0.0
pyverge migrate data.json --manager user --to latest
pyverge diff --manager user --from 1.0.0 --to 2.0.0
pyverge export --manager user --version 2.0.0 > schema.json

Features

• Versioned model registry — decorator-based registration with semver or ISO date versioning
• Model reflection — when a migration endpoint has no concrete model, the engine reconstructs it from the other endpoint's model and the migration diff (on_missing_model="reconstruct"), so every version in a chain is materializable
• Provider adapters — pluggable ModelAdapter; Pydantic and JSON Schema ship today, other providers (dataclasses, attrs, marshmallow, MessagePack) plug in the same way
• Declarative migrations — express a migration as an RFC 6902 JSON Patch op list (plus set_default/coerce/map/split), compiled into a MigrationFunc via JsonPatchMigration
• Convergent migration engine — graph-driven, with automatic migration of nested versioned entries
• Target policies — converge to latest, earliest, a pinned version, or per-kind overrides
• Executors — sequential or level-parallel batch convergence
• Model diffing — breaking-change detection with JSON Patch rendering
• Migration hooks — observability via before/after/error callbacks, plus an OpenTelemetry hook

Documentation

• Getting Started
• Registration
• Concepts
• Execution Flow
• Target Policy
• Model Reflection
• Telemetry & Hooks
• Common Usage Patterns
• Scenarios
• Showcases

Plan

Items intentionally out of scope for this documentation pass, tracked here for follow-up:

• CLI/manager facade alignment — ModelManager now exposes get, get_latest, and list_versions. The CLI still expects validate_data, diff, list_models, dump_schemas, and migrate(data, schema, from_version, to_version) before those commands work end-to-end.
• Additional model providers — adapters for dataclasses, attrs, marshmallow, and MessagePack
• Real-source integrations — showcases/ projects wiring for document storage (converge on read), Kafka consumers, RabbitMQ/streams workers, and MQTT/IoT gateways on the high-level ModelManager API, with thin adapters around real drivers (motor, confluent-kafka, aio-pika, paho-mqtt). The transport glue is not shipped yet.
• API reference — an auto-generated API reference page will be restored once the SDK surface is stable.