spltz-viur-actions 0.3.0

Action-based request handling and workflow engine for ViUR modules.

viur-actions

Action-based request handling for ViUR modules.

Features

• @action decorator and ActionModule mixin
• Class-init hook wiring (can<X> / on<X> / then<X> / <X>Skel), falling back to the suffix-less defaults (can / on / then / skel)
• Envelope-v2 via a versioned renderer — mounted under /json/v2/ · /vi/v2/ by install(), selected per-URL. No monkey-patch, no global switch. By default the unversioned /json/ · /vi/ follow the newest version (v2); pass alias_to_newest=False to keep them on v1.

Multi-step workflows (drafts, sliding TTL, optimistic locking, cleanup task) live in the sibling viur-workflow package. See CHANGELOG.md for the running summary.

Requirements

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

Install

pip install spltz-viur-actions

Quick taste

Serve the envelope by mounting the versioned renderer after setup():

from viur.core import setup
import viur.actions
import modules

app = setup(modules)
viur.actions.install()          # mounts /json/v2/… + /vi/v2/…; unversioned /json/ · /vi/ follow v2

Declare actions and hooks on a module:

from viur.core.prototypes import List
from viur.actions import action, ActionModule

class Example(ActionModule, List):

    @action
    def edit(self, key, **kwargs):
        ...

    # Fallback hooks — every action without specific hooks lands here.
    # (No `skel`: on a SkelModule viur-core's own `skel` is the base
    #  skeleton factory, so defining one here would shadow it and recurse.)
    def can(self, skel): ...
    def on(self, skel): ...
    def then(self, skel): ...

    # Action-specific overrides — picked up automatically:
    def canEdit(self, skel): ...
    def editSkel(self): ...

The class-init wiring (__init_subclass__) checks at class definition time which hooks the module provides, and resolves missing ones to the suffix-less default chain. Lookup at runtime is constant-time.

Note: these hooks are resolved for your own @action bodies (via the runtime helpers). viur-core's built-in view/edit/… still call their own canView/onEdited/… directly — can is not a global policy for them.

Development

Two test layers, run separately:

Unit (fast, mocked) — tests/, 100 % coverage gate:

git clone https://github.com/sprengplatz/viur-actions
cd viur-actions
pip install --no-deps -e .
pip install pytest pytest-cov 'coverage[toml]' 'spltz-viur-light-mock>=0.2.0'
pytest                  # 100% coverage required

spltz-viur-light-mock provides the viur.core.* stand-ins so these run without the App Engine stack.

Integration (real core) — integration/, no coverage gate:

pip install "viur-core>=3.8,<4" rsa pytest      # NOT spltz-viur-light-mock
pip install --no-deps -e .
python -m pytest -c integration/pytest.ini integration

Runs the envelope + signature-parity tests against the real framework — the layer that catches mock-vs-core drift. See integration/README.md.

Coverage policy. The 100 % gate applies to the unit layer only. The integration layer runs without a coverage requirement — a coverage target there would pressure mocking the very framework it exists to exercise.

License

MIT — see LICENSE.