Own the room's working objects

Prerequisite: Rift setup. The workstation is the room's local binding canvas. It holds objects, attributes, and methods you give it; it is not another Spellbook or an implicit resolver.

The saved example binds the name subject in both the object and method stores. The store= argument distinguishes them. It selects a method as the active target, calls it, clears the target without deleting the binding, and releases the object.

Be explicit about retention

weak_ref=True requests weak storage. The lesson proves a non-weak-referenceable value is refused rather than silently stored strongly. A strong binding retains the object for the binding's lifetime; a weak binding does not give it that lifetime.

Keep room storage and world access separate. Retrieve permitted world objects through the room's command/view surfaces, then place the objects you need on the canvas. Expert rooms continue into operation and codegen.

The workflow in code

These are the core steps from the saved example. Use its complete linked script for all class definitions and setup.

def main() -> None:
    nexus = md.Nexus()
    system_config = nexus.create_configuration()
    system_config.with_rift_creation_enabled(True)
    nexus.activate(system_config)

    rift_config = nexus.create_rift_configuration()
    rift_config.with_space_type("capability")
    rift = nexus.create_rift(configuration=rift_config, rift_name="bench")
    rift.mark_active()

    workstation = rift.space.workstation
    assert isinstance(workstation, md.Workstation)
    assert workstation.owner_space_id == rift.space.space_id
    print("workstation:", workstation.workstation_id)
    print("owned by room:", workstation.owner_space_id == rift.space.space_id)

    # THREE STORES. The same name in two stores is not a collision.
    greeter = Greeter()
    workstation.bind_object("subject", greeter)
    workstation.bind_method("subject", greeter.greet)
    print("bound 'subject' into two different stores")

    from_objects = workstation.get("subject", store="objects")
    from_methods = workstation.get("subject", store="methods")
    assert from_objects is greeter
    assert from_methods() == "hello from the canvas"
    print("objects['subject'] is the instance; methods['subject'] is callable")

    # THE READ DOOR. Ask the canvas what is on it.
    summary = workstation.describe_bindings()
    print("describe_bindings keys:", sorted(summary))
    for store in ("objects", "attributes", "methods", "target_name"):
        assert store in summary, store
    assert "subject" in summary["objects"]
    assert "subject" in summary["methods"]

    # Five keys, and the docstring now says five. `target_store` names the
    # store the active target came from - enough to round-trip it back
    # through get(name, store=...).
    assert set(summary) == {"objects", "attributes", "methods",
                            "target_name", "target_store"}
    print("keys:", len(summary), "- documented and returned agree")

    # ONE TARGET AT A TIME.
    workstation.set_target("subject", store="methods")
    assert workstation.get_target() is not None
    print("target set from the methods store")

    result = workstation.call_target()
    assert result == "hello from the canvas"
    print("call_target ->", result)

    workstation.clear_target()
    # Clearing deselects; it does not delete the binding underneath.
    assert workstation.get("subject", store="methods") is not None
    print("target cleared; the binding it pointed at is still there")

    # WEAK BY REQUEST. A class instance can be weak-referenced.
    workstation.bind_object("weak_subject", Greeter(), weak_ref=True)
    print("weak binding accepted for a weak-referenceable object")

    # ...and an int cannot. This RAISES rather than quietly storing it
    # strongly, which is the whole point.
    try:
        workstation.bind_object("weak_number", 42, weak_ref=True)
        raise AssertionError(
            "expected a refusal - int cannot be weak-referenced"
        )
    except (TypeError, ValueError, RuntimeError) as error:
        print("explicit weak binding refused:", type(error).__name__)

    # No silent degrade means: it is not on the canvas at all.
    after = workstation.describe_bindings()
    assert "weak_number" not in after["objects"]
    print("refused binding was NOT stored strongly as a fallback")

    # release() takes it back off the canvas and hands it to you.
    released = workstation.release("subject", store="objects")
    assert released is greeter
    assert "subject" not in workstation.describe_bindings()["objects"]
    print("released 'subject' from objects; methods copy untouched:",
          "subject" in workstation.describe_bindings()["methods"])

    print()
    print("the canvas holds; the command system resolves. separate jobs.")
    print("weak when asked, never by accident - refuse instead of degrade")

Runnable examples

The workstation canvas — Advanced 12
Static vs capability authority — Advanced 11

All advanced examples · Level contents · Full contents

Canonical page source