spltz-viur-revision 0.1.0

Automatic revision tracking and rollback for ViUR skeletons.

viur-revision

Automatic revision tracking and rollback for ViUR skeletons.

What it does

viur-revision snapshots the pre-write state of any tracked skeleton into a companion datastore kind (<kind>_revision) on every write. Each revision entity carries:

• a verbatim copy of all original entity properties
• origin_key — the original entity's key
• revision_index — monotonically increasing counter per origin
• revision_date — UTC timestamp of the snapshot
• revision_change_list — bone names that changed in this write

The package adds endpoints to list, view, restore, and delete revisions, plus a tiered retention task that thins out the history over time.

Requirements

• Python ≥ 3.12
• viur-core ≥ 3.7, < 4

Install

pip install spltz-viur-revision

Usage

1. Make a skeleton track revisions

from viur.revision import RevisionAbstractSkel

class ExampleSkel(RevisionAbstractSkel, Skeleton):
    # Track every write (default):
    pass

Or only react to changes on specific bones:

class ExampleSkel(RevisionAbstractSkel, Skeleton):
    revision_fields = ["title", "body"]

2. Expose revision endpoints on the module

from viur.revision import RevisionModule

class Example(RevisionModule, List):
    ...

This adds:

• GET /<module>/list_revision?key=<entity-key>
• GET /<module>/view_revision?key=<entity-key>&version=<n|latest>
• POST /<module>/apply_revision (skey-protected)
• POST /<module>/delete_revision (skey-protected)
• GET /<module>/cleanup_revisions_now (manual retention run)

All endpoints require either the root right or <moduleName>-manage.

3. Retention

A daily PeriodicTask thins history per origin_key:

Age	Retention
< 24h	keep all
1d–7d	1 per hour (latest)
7d–30d	1 per day (latest)
> 30d	1 per week (latest)

Documentation

Full reference at sprengplatz.github.io/viur-revision.

Development

git clone https://github.com/sprengplatz/viur-revision
cd viur-revision
pip install -e ".[dev]"
pytest                  # 100% coverage required
mkdocs serve            # docs at http://localhost:8000

License

MIT — see LICENSE.