Survey first, then choose detail

Prerequisite: opening a Rift. Start at rift.space.frame_viewer. The host-level multi-frame view can enumerate frames without selecting one. The frame, conduit, and spell views require a frame name.

Control the amount you read

Use list_* to discover names and IDs, a brief description to decide what matters, then detail or a specific facet for the selected object. For spells, the ladder is describe_spell_brief, describe_spell, describe_spell_detail, and describe_spell_payload. Source, binding, identity, resolution, and research reads let a caller request a particular concern.

The viewer lessons inspect the method surface and show that a fresh Rift can have an empty assigned-frame set. An empty survey is different from a frame-local request that lacks the required target.

Missing is not always absent

A visibility-filtered description may omit a section because it does not exist or because this Rift may not see it. Use the missing-section/visible-surface probes to understand that boundary. They report withheld section names without exposing their hidden payload bodies.

On the facade, frame_name selects the frame. On a view already bound to a frame, an optional frame name can instead be an assertion that it matches. Read the specific signature rather than treating those two surfaces as interchangeable.

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="observatory")
    rift.mark_active()

    viewer = rift.space.frame_viewer
    assert isinstance(viewer, md.FrameViewer)
    print("viewer:", viewer.id)

    # THE FACADE'S COMMON READS. A fresh rift has no assigned frames yet,
    # so these are honest zeros rather than errors - the read surface
    # works on an empty world.
    frame_names = viewer.list_frame_names()
    print("frames visible:", viewer.count_frames(), frame_names)
    assert isinstance(frame_names, list)
    assert viewer.count_frames() == len(frame_names)

    # THE VIEWS SPLIT INTO TWO GROUPS, AND THAT SPLIT IS THE LESSON.
    #
    # get_view_multiframe() is HOST-SCOPED - it asks about all frames, so
    # it needs no frame name and works right now.
    multiframe = viewer.get_view_multiframe()
    assert isinstance(multiframe, md.ViewMultiFrame)
    print("view_multiframe:", type(multiframe).__name__, "(host-scoped)")

    # get_view_frame / get_view_conduit / get_view_spell are FRAME-SCOPED.
    # THERE IS NO DEFAULT FRAME, and since the signature fix that is now
    # enforced by the signature itself - omitting the name is a TypeError
    # at the call, not a ValueError from somewhere inside.
    for accessor in ("get_view_frame", "get_view_conduit", "get_view_spell"):
        try:
            getattr(viewer, accessor)()
            raise AssertionError(f"{accessor} should require a frame name")
        except TypeError as error:
            print(f"  {accessor:18s} requires a frame name: {error}")

    # This rift is contracted to no frames, so there is no name to pass -
    # which is the honest state of a freshly opened rift.
    assert rift.list_assigned_frame_names() == ()
    print("assigned frames:", rift.list_assigned_frame_names(),
          "- nothing to scope a frame-local view to yet")

    # The view TYPES are still inspectable without an instance, which is
    # how the next two lessons map their surfaces.
    for view_type in (md.ViewFrame, md.ViewConduit, md.ViewSpell,
                      md.ViewMultiFrame):
        assert isinstance(view_type, type)
    print("four view types exported:", ", ".join(
        t.__name__ for t in (md.ViewFrame, md.ViewConduit, md.ViewSpell,
                             md.ViewMultiFrame)))

    # NO CACHED SNAPSHOT. The facade resolves per invocation, so two calls
    # hand back two view objects rather than one memoized one.
    assert viewer.get_view_multiframe() is not viewer.get_view_multiframe()
    print("fresh view per invocation - nothing to go stale")

    # WHAT VIEWS EXIST? Ask, do not assume.
    available = viewer.describe_available_views()
    assert isinstance(available, list)
    print("describe_available_views ->", len(available), "entries")

    # THE AIX SURFACE. The viewer describes its own method surface...
    surface = viewer.describe_viewer_method_surface()
    assert isinstance(surface, dict)
    print("describe_viewer_method_surface ->", len(surface), "keys")

    # ...and onboards an agent in JSON, at runtime, from the object itself.
    onboarding = viewer.describe_agent_onboarding_json()
    assert isinstance(onboarding, str)
    parsed = json.loads(onboarding)
    print("describe_agent_onboarding_json -> valid JSON,",
          len(onboarding), "chars")
    print("  top-level keys:", sorted(parsed)[:6])

    purpose = viewer.describe_viewer_agent_purpose_json()
    assert isinstance(purpose, str)
    json.loads(purpose)
    print("describe_viewer_agent_purpose_json -> valid JSON")

    # clone() hands back an independent facade over the same world.
    twin = viewer.clone()
    assert isinstance(twin, md.FrameViewer)
    assert twin is not viewer
    assert twin.count_frames() == viewer.count_frames()
    print("clone: independent object, same reading")

    print()
    print("a facade with no snapshot - every read is a fresh resolve")
    print("and the object onboards its own caller instead of assuming docs")

Runnable examples

The frame viewer facade — Advanced 13
The describe ladder — Advanced 14
What you cannot see — Advanced 15

All advanced examples · Level contents · Full contents

Canonical page source