Skip to content

README.md

Latest commit

 

History

History
176 lines (132 loc) · 5.68 KB

README.md

File metadata and controls

176 lines (132 loc) · 5.68 KB
Raw

VMx Python Examples

Four self-contained demos of the VMx Python library. Generated architecture diagrams for all examples live in ../DIAGRAMS.md.

1. Setup

The console and tkinter examples share the root examples/python environment. Each Textual example is a standalone uv project with its own environment and lockfile, as shown in its section below.

cd examples/python
uv sync          # prepares the console + tkinter environment

2. Example 1 — console/hello_vmx (console)

Minimal console demo. Demonstrates:

  1. Building a ComponentVMOf[UserModel] with the fluent builder.
  2. Subscribing to hub messages (ConstructionStatusChangedMessage + PropertyChangedMessage).
  3. The full lifecycle: construct → model mutations → destruct → dispose.
  4. The equality guard: setting the same model value emits no hub message.

Run:

Diagram: python-console-hello-vmx.svg (HTML, PNG).

cd examples/python
uv run python -m hello_vmx

Expected output (truncated):

=== hello_vmx ===

Building ComponentVMOf[UserModel] ...
  vm.name   = user-vm
  vm.status = DESTRUCTED
  vm.model  = UserModel(name='Alice', age=30)

Calling construct() ...
  [hub] user-vm  status → CONSTRUCTING
  ...
  vm.is_constructed = True
  vm.modeled_hint   = 'Alice (30)'

Mutating model → Bob, 25 ...
  [hub] user-vm  property 'model' changed
  ...

Setting the SAME model value (equality guard — no hub message expected) ...

=== Done ===

3. Example 2 — tk/todo_app (tkinter MVVM)

Full MVVM todo app using tkinter. Demonstrates:

  • TodoItemVM — subclasses ComponentVMOf[TodoItem]; adds a toggle_done RelayCommand.
  • MainWindowViewModel — holds a CompositeVM[TodoItemVM]; exposes add_command and remove_command.
  • MainWindow — pure view; all logic lives in the ViewModel.

Run (requires a display):

Diagram: python-tk-todo-app.svg (HTML, PNG).

cd examples/python
uv run python -m todo_app

Headless import check:

cd examples/python
uv run python -c "from todo_app.__main__ import MainWindow; print('OK')"

4. Example 3 — textual/inspector (Textual TUI)

A general-purpose live inspector for any VMx hierarchy. Demonstrates:

  • vmx.tree.walk driving a textual.widgets.Tree view of the VM hierarchy.
  • A DataTable log subscribed to hub.messages, showing every PropertyChangedMessage and ConstructionStatusChangedMessage as it fires.
  • Lifecycle keybindings (c construct, d destruct, r reconstruct, x dispose, s select) on the highlighted node.

textual/inspector/ is its own uv project (Textual is a heavier dependency than the other two examples) — run it from its own directory:

Diagram: python-textual-inspector.svg (HTML, PNG).

uv run --project examples/python/textual/inspector python -m vmx_inspector

5. Example 4 — textual/notes_showcase (Textual TUI, flagship)

The Notes Workspace flagship app — a TUI on Textual ≥ 0.80 that exercises 19 distinct VMx features in one cohesive scenario (notebooks tree, paged + filterable notes list, FormVM editor, capability-aware action bar, notifications, async lifecycle, dialogs, AggregateVM6 root, and the v2.4.0 ThemeVM scenario contract, plus token-paged global search, edit/preview state, and tag autocomplete). Pure-VM contract enforced; widget classes expose only compose() / on_mount() / one-statement action_*().

textual/notes_showcase/ is its own uv project — run it from the repo root:

Diagram: python-textual-notes-showcase.svg (HTML, PNG).

uv run --project examples/python/textual/notes_showcase python -m notes_showcase

See textual/notes_showcase/README.md for project layout, feature-traceability, and keybindings (Ctrl+S to save, Ctrl+F to search, etc.). Cross-flavor parity is documented in ../notes-showcase-parity.md; the canonical scenario contract lives at ../../spec/proposals/2026-05-29-notes-showcase-scenario.md.

6. Project layout

examples/python/
├── pyproject.toml              # shared deps (vmx local path via uv.sources)
├── README.md                   # this file
├── console/
│   └── hello_vmx/
│       ├── __init__.py
│       └── __main__.py         # entry point: python -m hello_vmx
├── tk/
│   └── todo_app/
│       ├── __init__.py
│       └── __main__.py         # entry point: python -m todo_app
└── textual/
    ├── inspector/              # stand-alone uv project (Textual)
    │   ├── pyproject.toml
    │   ├── README.md
    │   ├── src/vmx_inspector/
    │   └── tests/
    └── notes_showcase/         # stand-alone uv project (Textual flagship)
        ├── pyproject.toml
        ├── README.md
        ├── src/notes_showcase/
        └── tests/