migration

Version: 10.1.14

wexample-migration is a Python library for running versioned, sequenced migrations against a caller-owned workdir. Each migration is a subclass of AbstractMigration that declares a VERSION and SEQ; a MigrationRunner applies, rolls back, or reports on them through a MigrationContext that carries the target path, a dry_run flag, and the read_stamp/write_stamp callables the consumer injects. Stamp persistence is left entirely to the caller, so the library stays decoupled from any particular storage backend and can be embedded in any Python application that needs to evolve stateful workdirs across versions.

Table of Contents

• Installation
• Quickstart
• Tests
• Architecture
• Integration in the Suite
• Dependencies
• Versioning & Compatibility Policy
• License
• About us
• Known Limitations & Roadmap
• Status & Compatibility
• Useful Links
• Migration Notes

Installation

pip install wexample-migration

Requires Python >=3.10.

Quickstart

Install the package:

pip install wexample-migration

Define one migration class per change. Set VERSION (semver string) and implement apply:

from wexample_migration.abstract_migration import AbstractMigration
from wexample_migration.migration_context import MigrationContext

class AddConfigDir(AbstractMigration):
    VERSION = "1.0.0"
    DESCRIPTION = "Create the config directory"

    def apply(self, context: MigrationContext) -> None:
        (context.target_path / "config").mkdir(exist_ok=True)

MigrationContext takes the path being migrated and two callables — read_stamp and write_stamp — that you supply. The runner never touches storage directly:

from pathlib import Path
from wexample_migration.migration_context import MigrationContext
from wexample_migration.migration_runner import MigrationRunner
from wexample_migration.migration_stamp import MigrationStamp

class StampStore:
    def __init__(self) -> None:
        self.stamp: MigrationStamp | None = None

    def read(self) -> MigrationStamp | None:
        return self.stamp

    def write(self, stamp: MigrationStamp) -> None:
        self.stamp = stamp

store = StampStore()
context = MigrationContext(
    target_path=Path("/path/to/workdir"),
    read_stamp=store.read,
    write_stamp=store.write,
)

runner = MigrationRunner(migrations=[AddConfigDir])
applied = runner.run(context)
# applied == ["1.0.0-1"]
# /path/to/workdir/config/ now exists
# store.stamp == MigrationStamp(version="1.0.0", seq=1)

runner.run returns the labels of every migration it applied. A second call with the same context returns [] — migrations at or below the current stamp are skipped automatically.

To inspect what would run without touching the workdir or writing the stamp, pass dry_run=True:

context = MigrationContext(
    target_path=Path("/path/to/workdir"),
    read_stamp=store.read,
    write_stamp=store.write,
    dry_run=True,
)
would_apply = runner.run(context)
# would_apply == ["1.0.0-1"] — nothing written, stamp unchanged

Tests

This project uses pytest for testing and pytest-cov for code coverage analysis.

Installation

First, install the required testing dependencies:

.venv/bin/python -m pip install pytest pytest-cov

Basic Usage

Run all tests with coverage:

.venv/bin/python -m pytest --cov --cov-report=html

Common Commands

# Run tests with coverage for a specific module
.venv/bin/python -m pytest --cov=your_module

# Show which lines are not covered
.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing

# Generate an HTML coverage report
.venv/bin/python -m pytest --cov=your_module --cov-report=html

# Combine terminal and HTML reports
.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing --cov-report=html

# Run specific test file with coverage
.venv/bin/python -m pytest tests/test_file.py --cov=your_module --cov-report=term-missing

Viewing HTML Reports

After generating an HTML report, open htmlcov/index.html in your browser to view detailed line-by-line coverage information.

Coverage Threshold

To enforce a minimum coverage percentage:

.venv/bin/python -m pytest --cov=your_module --cov-fail-under=80

This will cause the test suite to fail if coverage drops below 80%.

Architecture

The package is a thin, storage-agnostic migration engine. It has four core types, one optional base class, and one workdir mixin. Nothing in the library touches the filesystem for persistence — that responsibility belongs entirely to the consumer.

Core types

MigrationStamp — src/wexample_migration/migration_stamp.py

A NamedTuple with two fields: version (semver string, e.g. "6.0.21") and seq (integer or None). seq=None means "past every migration of this version" and is used for legacy stamps that predate per-sequence tracking. stamp_sort_key(version, seq) converts those two fields into a comparable tuple used everywhere ordering matters; seq=None maps to math.inf so it sorts after every finite seq.

MigrationContext — src/wexample_migration/migration_context.py

The parameter bag threaded through the runner and into every migration's apply(). It carries:

• target_path — root Path of the workdir being migrated
• dry_run — when True, migrations run but write_stamp is never called and no filesystem writes should occur
• extras — untyped dict for caller-specific data (kernel, workdir reference, …); the package never reads it
• read_stamp — Callable[[], MigrationStamp | None] supplied by the consumer
• write_stamp — Callable[[MigrationStamp], None] supplied by the consumer

AbstractMigration — src/wexample_migration/abstract_migration.py

Base class for every migration. Subclasses set three class variables:

VERSION: ClassVar[str] = "6.0.21"
SEQ: ClassVar[int] = 1          # distinguishes sibling migrations of the same VERSION
DESCRIPTION: ClassVar[str] = ""

and implement apply(context). Three optional hooks exist:

• rollback(context) — no-op by default; override to undo apply
• is_applicable(context) -> bool — return False to skip this migration at runtime
• guess_version(context) -> bool — bootstrap fallback for legacy workdirs with no stamp; return True if the workdir state matches this migration's version

MigrationRunner — src/wexample_migration/migration_runner.py

Holds the list of migration classes and exposes three operations:

• run(context) — applies all pending migrations in order; returns the labels applied
• rollback(context) — calls rollback() on the migration matching the current stamp, then writes the previous stamp
• status(context) — returns a dict with current_version, current_seq, applied, and pending; reads nothing else

Ordering is always determined by stamp_sort_key(VERSION, SEQ) — the list passed to MigrationRunner can be in any order.

Optional base class

FilestateItemMigration — src/wexample_migration/filestate/filestate_item_migration.py

A convenience subclass of AbstractMigration for migrations that declare a desired filesystem state. Subclasses implement get_filestate_config(context) -> DictConfig and return a wexample-filestate configuration dict. The apply() implementation builds a FileStateManager rooted at context.target_path, honours context.dry_run, and delegates the operation pipeline to wexample-filestate.

Workdir mixin

WithMigrationWorkdirMixin — src/wexample_migration/workdir/mixin/with_migration_workdir_mixin.py

Mix this into a workdir class to add migration_run(), migration_status(), and migration_rollback() without touching MigrationRunner directly. The mixin builds the MigrationContext from the workdir's own get_path(), migration_read_stamp(), and migration_write_stamp() — three methods the workdir subclass must override to wire in its storage backend.

Call path through a migration_run()

1. Consumer calls workdir.migration_run(dry_run=False).
2. WithMigrationWorkdirMixin._build_migration_context() constructs a MigrationContext, binding read_stamp and write_stamp to the workdir's overrides.
3. MigrationRunner.run(context) calls context.read_stamp(). If the result is None, _bootstrap_stamp() iterates migrations in reverse and calls each one's guess_version(context) to detect a legacy workdir; the first that returns True becomes the current stamp.
4. _pending_migrations() filters the sorted migration list to those whose stamp_sort_key is strictly greater than the current stamp's key.
5. For each pending class: instantiate it, call is_applicable(context); if False, skip. Otherwise, if not dry_run, call migration.apply(context) then context.write_stamp(MigrationStamp(version, seq)).
6. Return the list of applied labels.

Package layout

src/wexample_migration/
├── abstract_migration.py          # AbstractMigration base class
├── migration_context.py           # MigrationContext parameter bag
├── migration_runner.py            # MigrationRunner (run / rollback / status)
├── migration_stamp.py             # MigrationStamp + stamp_sort_key
├── filestate/
│   └── filestate_item_migration.py  # FilestateItemMigration (filestate bridge)
└── workdir/
    └── mixin/
        └── with_migration_workdir_mixin.py  # WithMigrationWorkdirMixin

Integration in the Suite

This package is part of the Wexample Suite — a collection of high-quality, modular tools designed to work seamlessly together across multiple languages and environments.

Related Packages

The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.

Visit the Wexample Suite documentation for the complete package ecosystem.

Dependencies

• attrs: >=23.1.0
• cattrs: >=23.1.0
• pyyaml: >=6.0
• wexample-filestate: >=17.5.0
• wexample-helpers: >=20.3.0

Versioning & Compatibility Policy

Wexample packages follow Semantic Versioning (SemVer):

• MAJOR: Breaking changes
• MINOR: New features, backward compatible
• PATCH: Bug fixes, backward compatible

We maintain backward compatibility within major versions and provide clear migration guides for breaking changes.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Free to use in both personal and commercial projects.

About us

Wexample stands as a cornerstone of the digital ecosystem — a collective of seasoned engineers, researchers, and creators driven by a relentless pursuit of technological excellence. More than a media platform, it has grown into a vibrant community where innovation meets craftsmanship, and where every line of code reflects a commitment to clarity, durability, and shared intelligence.

This packages suite embodies this spirit. Trusted by professionals and enthusiasts alike, it delivers a consistent, high-quality foundation for modern development — open, elegant, and battle-tested. Its reputation is built on years of collaboration, refinement, and rigorous attention to detail, making it a natural choice for those who demand both robustness and beauty in their tools.

Wexample cultivates a culture of mastery. Each package, each contribution carries the mark of a community that values precision, ethics, and innovation — a community proud to shape the future of digital craftsmanship.

Known Limitations & Roadmap

Current limitations and planned features are tracked in the GitHub issues.

See the project roadmap for upcoming features and improvements.

Status & Compatibility

Maturity: Production-ready

Python Support: >=3.10

OS Support: Linux, macOS, Windows

Status: Actively maintained

Useful Links

• Homepage: https://github.com/wexample/python-migration
• Documentation: docs.wexample.com
• Issue Tracker: https://github.com/wexample/python-migration/issues
• Discussions: https://github.com/wexample/python-migration/discussions
• PyPI: pypi.org/project/wexample-migration

Migration Notes

When upgrading between major versions, refer to the migration guides in the documentation.

Breaking changes are clearly documented with upgrade paths and examples.