Metadata-Version: 2.1
Name: wexample-migration
Version: 10.1.10
Summary: Runs versioned, sequenced migrations with rollback and dry-run support, keeping stamp persistence in the caller's hands
Author-Email: weeger <contact@wexample.com>
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Requires-Dist: attrs>=23.1.0
Requires-Dist: cattrs>=23.1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: wexample-filestate>=17.2.0
Requires-Dist: wexample-helpers>=20.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
Requires-Dist: pytest>=9.0.2; extra == "dev"
Description-Content-Type: text/markdown

# migration

Version: 10.1.10

`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](#installation)
- [Quickstart](#quickstart)
- [Tests](#tests)
- [Architecture](#architecture)
- [Integration in the Suite](#integration-in-the-suite)
- [Dependencies](#dependencies)
- [Versioning & Compatibility Policy](#versioning--compatibility-policy)
- [License](#license)
- [About us](#about-us)
- [Known Limitations & Roadmap](#known-limitations--roadmap)
- [Status & Compatibility](#status--compatibility)
- [Useful Links](#useful-links)
- [Migration Notes](#migration-notes)

## Installation

```bash
pip install wexample-migration
```

Requires Python >=3.10.

## Quickstart

Install the package:

```bash
pip install wexample-migration
```

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

```python
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:

```python
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`:

```python
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:
```bash
.venv/bin/python -m pip install pytest pytest-cov
```

### Basic Usage

Run all tests with coverage:
```bash
.venv/bin/python -m pytest --cov --cov-report=html
```

### Common Commands
```bash
# 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:
```bash
.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:

```python
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](https://docs.wexample.com) for the complete package ecosystem.

## Dependencies

- attrs: >=23.1.0
- cattrs: >=23.1.0
- pyyaml: >=6.0
- wexample-filestate: >=17.2.0
- wexample-helpers: >=20.0.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](LICENSE) file for details.

Free to use in both personal and commercial projects.

## About us

[Wexample](https://wexample.com) 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](https://github.com/wexample/python-migration/issues) 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](https://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](https://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.
