vmx — Python

Hierarchical lifecycle-aware MVVM viewmodel framework for Python, spec-compatible with the C#, TypeScript, Swift, and Rust flavors.

1. Status

v3.23.0 — implements spec-v3.23.0 end-to-end. 403/403 library conformance IDs pass. Supports Python 3.10–3.14. mypy --strict clean. Opt-in vmx.notifications subpackage ships an INotificationHub for async confirmations. The Swift flavor is at total parity; see ../swift/README.md §5 for the current conformance matrix.

2. Install

The source tree currently implements v3.23.0. The latest public PyPI package may lag this source tree; pin a version when reproducing released behavior.

pip install vmx
# or
uv add vmx

3. Quick start

The minimum-viable shape is imports → services → builder (name + model + services + optional modeled_hinter) → construct() → read status:

from dataclasses import dataclass

from vmx import (
    ComponentVMOf,
    CompositeVM,
    MessageHub,
    RxDispatcher,
)


@dataclass
class TabModel:
    title: str


# 1. Services (a hub + a dispatcher).
hub = MessageHub()
dispatcher = RxDispatcher.immediate()

# 2. Build leaves: name, model, services, optional modeled_hinter.
home: ComponentVMOf[TabModel] = (
    ComponentVMOf.builder()
    .name("home")
    .model(TabModel("Home"))
    .modeled_hinter(lambda m: m.title)  # optional — defaults to lambda _m: ""
    .services(hub, dispatcher)
    .build()
)

settings: ComponentVMOf[TabModel] = (
    ComponentVMOf.builder()
    .name("settings")
    .model(TabModel("Settings"))
    .services(hub, dispatcher)
    .build()
)

# 3. Build a composite over the leaves.
tabs = (
    CompositeVM[ComponentVMOf[TabModel]]
    .builder()
    .name("tab-bar")
    .services(hub, dispatcher)
    .children(lambda: [home, settings])
    .build()
)

# 4. Transition the lifecycle from DESTRUCTED → CONSTRUCTED before use.
tabs.construct()
print(tabs.status)  # ConstructionStatus.CONSTRUCTED

tabs.current = settings
print(tabs.current.model.title)  # "Settings"

tabs.dispose()
hub.dispose()

Tips:

• .modeled_hinter(...) is optional on every modeled builder; the default is lambda _m: "". Pass a callable when you want to derive a display hint from the model.
• For tests, samples, and headless code, NULL_MESSAGE_HUB and NULL_DISPATCHER are safe no-op singletons. Annotate variables as MessageHubProto[Message] (the structural Protocol) to keep mypy --strict happy, or use the generic null_message_hub_of(MyMessage) factory (imported from vmx.services) for a narrower message type.

The C# and TypeScript flavors mirror this shape: see C# Quick start and TypeScript Quick start — only the identifier casing differs.

See Getting Started with VMx — Python for the full walkthrough.

3.1 Cross-language naming

The conceptual surface is identical across the five flavors; identifier casing follows the per-language idiom (see ADR-0006).

C# uses PascalCase, Python and Rust use snake_case, TypeScript and Swift use camelCase. C# and Rust retain the same public type name for modeled and unmodeled components (ComponentVM<M> / ComponentVm<M>), while Python, TypeScript, and Swift use a separate ComponentVMOf type because their generics syntax cannot overload an unparameterised name.

4. API surface

The public API is re-exported from a single entry point:

from vmx import ComponentVM, ConstructionStatus, MessageHub, RelayCommand, RxDispatcher

4.1 Serviced collections

Use ServicedObservableCollection[T] for a caller-owned sequence with local on_collection_changed delivery and optional hub publication:

notes = ServicedObservableCollection[Note](hub)
notes.append(first)
notes.append(second)
removed = notes.remove_at(-1)
old = notes.replace(-1, revised)
notes.append(second)
notes.move(0, len(notes) - 1)  # strict, nonnegative positions
notes.replace_all(server_snapshot)  # one Reset

List-style remove(value) removes the first match, returns None, and raises ValueError when missing. remove_at / replace accept normal negative list indices and return the removed / old item; move rejects negative or out-of-range positions with IndexError. Empty Clear and empty-to-empty replacement are no-ops. Messages expose index, old_index, and new_index; the collection does not batch or own items. Use ObservableList[T] when you need batch scopes and the Count channel.

Choose KeyedServicedObservableCollection[TKey, T] for one stable domain-key index without giving up list order or the full MutableSequence surface:

notes_by_id = KeyedServicedObservableCollection[str, Note](lambda note: note.id, hub)
notes_by_id.append(first)
note = notes_by_id.get(first.id)
added = notes_by_id.upsert(revised)  # False: Replace at stable position
removed = notes_by_id.delete(first.id)

contains_key tests membership. Keys are captured until indexed replacement or delete-then-add; slice mutations and reverse() are atomic. Duplicate and projector failures preserve state. Lookup/target discovery are expected O(1), while ordered middle shifts remain O(n). Local delivery stays immediate even when an external hub transaction defers hub messages. Items remain caller-owned.

4.2 Imperative engine bridge

Use subscribe_value to push selected VM state into a renderer or other imperative host without polling it every frame:

from reactivex.abc import DisposableBase

from vmx import subscribe_value


def apply_exposure(exposure: float, _previous_exposure: float) -> None:
    material.uniforms.exposure.value = exposure


exposure_subscription: DisposableBase = subscribe_value(
    camera_vm,
    lambda vm: vm.model.exposure,
    apply_exposure,
    fire_immediately=True,
)

# When the host adapter is disposed:
exposure_subscription.dispose()

The callback receives (current, previous); immediate delivery passes the initial value for both. The selector runs after every property message from this fixed VM, and == suppresses unchanged selections. Pass equality= for custom equality. The host owns the returned DisposableBase; VMx does not attach it to the observed VM's lifetime.

The opt-in vmx.notifications subpackage (spec v2.0+) adds:

5. Conformance

All 403 library conformance IDs from spec/12-conformance.md are covered (the 5 THEME scenario IDs live in the flagship example apps — see CONTRIBUTING §2.5). Test-layout conventions for the conformance tree are documented in tests/conformance/README.md.

v1.x   LIFE-001..013  HUB-001..007  PROP-001..004  CMD-001..007
       CVM-001..010   COMP-001..013 GRP-001..006   AGG-001..005
       FWD-001..004   BLD-001..004  THR-001..004   UTIL-001..003
v2.0   CAP-001..020   NULL-001..003 DPROP-001..012 CMDD-001..009
       NOTIF-001..010 COMP-014..024 GRP-007..010   EXP-001..005
       LOC-001..003
v2.1   HIER-001..014  DIA-001..008  FORM-001..010  NOTIF-011..016
       COL-001..023   CMD-008..011  CAP-021..022
v2.2   AGG-006
v2.3   BLD-005        FORM-011..013 HIER-015..017
v2.4   THEME-001..005
v2.5   HIER-018       NOTIF-017     FORM-014
v2.6   COMP-025..026
v3.0   LIFE-014       FORM-015      CMDD-010      COMP-027      CMD-012
v3.1   CMD-013        COL-024..031  COMP-028..037 FORM-016..023
       DIA-009..013   HIER-019..022 DISC-001..006 BLD-006 GRP-011
v3.2   HUB-008..013
v3.3   CVM-007..009
v3.4   DISP-001..006
v3.5   COL-032..039
v3.6   CMD-014..019
v3.7   FORM-024..029
v3.8   HIER-023..030
v3.9   COL-040..047
v3.10  DISP-007..013
v3.11  DISP-014
v3.12  FORM-030
v3.15  SUBV-001..004
v3.16  COL-048..055
v3.17  COL-056..064
v3.18  AGCH-001..010

Run the suite:

uv run pytest

6. Development

# From this directory
uv sync --all-extras
uv run pytest
uv run ruff check
uv run ruff format --check
uv run mypy --strict src/vmx

The lifecycle-transitions.json fixture from spec/fixtures/ is tracked under src/vmx/lifecycle/_data/ and shipped inside the wheel. The vmx.lifecycle.transition_validator module loads it via importlib.resources with a repo-relative fallback for diagnostics. tools/check-python-fixture-sync.py keeps the package copy byte-identical to the spec fixture.

7. Releasing

See RELEASING.md for the PyPI release pipeline runbook.

8. License

Apache-2.0 — see LICENSE and NOTICE.