Getting started¶

Install¶

pip install spltz-viur-revision

Requires Python ≥ 3.12 and viur-core ≥ 3.7, < 4.

1. Track revisions on a skeleton¶

Inherit from RevisionAbstractSkel:

from viur.core.skeleton import Skeleton
from viur.revision import RevisionAbstractSkel

class ExampleSkel(RevisionAbstractSkel, Skeleton):
    kindName = "example"
    # … your bones …

By default, every write creates a new revision. To only react to changes on specific bones, set revision_fields:

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

revision_fields = ["*"] is the wildcard default — any non-empty change list triggers a revision.

Coalescing window¶

Rapid successive writes (e.g. auto-save) within a 15-minute window are merged into a single revision by default. Override per-skel:

import datetime

class ExampleSkel(RevisionAbstractSkel, Skeleton):
    # Disable coalescing entirely:
    revision_coalesce_window = None

    # Or shorten it:
    revision_coalesce_window = datetime.timedelta(minutes=2)

2. Expose revision endpoints on the module¶

from viur.revision import RevisionModule

class Example(RevisionModule, List):
    ...

This adds five endpoints under the module — see the RevisionModule API reference for the full request/response shapes:

Method	URL	Purpose
GET	`/<module>/list_revision`	List revisions
GET	`/<module>/view_revision`	View one revision
POST	`/<module>/apply_revision`	Restore a revision
POST	`/<module>/delete_revision`	Delete a single revision
GET	`/<module>/cleanup_revisions_now`	Run retention manually

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

3. Retention runs automatically¶

A daily PeriodicTask thins the history per origin entity. See Retention for the bucket logic.

Programmatic API¶

Load a specific revision into a viewSkel instance:

skel = self.viewSkel()
if not skel.read_revision(entity_key, version=3):
    raise errors.NotFound("Revision not found")

version="latest" (default) returns the most recent revision; pass an integer to select by revision_index.