On this page

• Workstation
  • Workstation
    • Workstation.cleanup()
    • Workstation.workstation_id
    • Workstation.owner_space_id
    • Workstation.bind_object()
    • Workstation.bind_attribute()
    • Workstation.bind_method()
    • Workstation.get()
    • Workstation.release()
    • Workstation.describe_bindings()
    • Workstation.set_target()
    • Workstation.get_target()
    • Workstation.clear_target()
    • Workstation.cleanup_target()
    • Workstation.call_target()

Workstation

Use md.Workstation from the public package namespace.

Implementation source

class Workstation(owner_space_id: str, *, default_weak_ref_bindings: bool = False, event_publisher: Callable[[Dict[str, object]], None] | None = None)

Internal

Room-local binding canvas owned by one RiftSpace.

Purpose:

Provide the local operating canvas inside one room where saved objects, saved attribute/value bindings, saved method/callable bindings, and the active target can be retained across steps.

Contract:

• Stores only room-local bindings; it does not discover or resolve new targets from Melder/Nexus.

• Keeps object, attribute/value, and method/callable bindings in separate logical stores.

• Each logical store supports both strong and weak backing storage.

• Bind calls accept weak_ref=True, weak_ref=False, or weak_ref=None.

• weak_ref=None resolves through the room-local default captured when this workstation is created.

• Explicit weak binding raises when the supplied value cannot be weak-referenced; it never silently degrades to strong storage.

• Tracks at most one active target binding at a time.

• cleanup_target(...) acts only on the currently selected target and then clears target selection.

• call_target(...) invokes the currently selected callable target and may bind the return value back into the workstation.

• Cleanup clears workstation-owned binding state but does not attempt to cleanup every stored binding automatically.

Lifecycle:

Owned by one RiftSpace. Cleanup is idempotent and clears binding stores plus active-target state.

Registration:

MELDER KERNEL - guarded. Created by the owning RiftSpace; users reach it through space.workstation.

Subsystem Context:

The BINDING CANVAS of a room, third beside FrameViewer (reads) and CommandSystem (mediated actions). Commands deliberately do not store results, so this is where anything worth keeping lands.

System Context:

The weak/strong storage model is the core of this class and it is where room posture becomes concrete. weak_ref=None resolves through the ROOM-LOCAL DEFAULT captured at construction - weak in static rooms, strong in capability rooms - so the same call in different rooms correctly produces different lifetime semantics without the caller restating policy. Explicit weak binding RAISES when a value cannot be weak-referenced and never silently degrades to strong. That refusal is the important one: a silent downgrade would hand back a binding whose lifetime contract is the opposite of what was requested, and the caller would have no way to detect it. Separating object, attribute, and method stores keeps those namespaces from colliding, and the single active target reflects that a room is one person's workspace - a canvas with several simultaneous "current" things would make every target-relative command ambiguous.

AGENT_ACCESS: public

AGENT_PURPOSE:

access: public. The room-local binding canvas (space.workstation): save objects, attribute and method bindings (strong or weak) and one active target across steps. Commands do not store their results, so this is where you keep what matters.

cleanup() → None

Internal

Idempotently clear workstation binding state.

Contract:

• Safe to call more than once.

• Clears strong and weak binding stores.

• Clears active-target state.

• Does not attempt to cleanup every stored binding automatically; explicit target cleanup is a separate operation.

Returns:

None.

property workstation_id: str

Return the stable workstation identifier.

Contract:

• Identifies THIS WORKSTATION, distinct from owner_space_id - the space that hosts it.

Threading:

Reads under self._lock, so the result is a coherent snapshot.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the object has been cleaned.

Returns:

Stable workstation id.

Return type:

str

property owner_space_id: str

Return the owning room identifier.

Contract:

• The rift space hosting this workstation, fixed at construction. A workstation is never re-homed to another space.

Threading:

Reads under self._lock, so the result is a coherent snapshot.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the object has been cleaned.

Returns:

Owning RiftSpace id.

Return type:

str

bind_object(name: str, value: object, *, weak_ref: bool | None = None) → None

Store one object binding by name.

Contract:

Delegates to the shared _bind(...) helper using the objects store and the requested reference mode.

Parameters:

• name -- Binding name.

• value -- Bound object value.

• weak_ref -- Explicit reference-mode override. True forces weak storage, False forces strong storage, and None uses the room-local workstation default.

Returns:

None.

Raises:

• ValueError -- If name is empty.

• TypeError -- If weak storage is requested for a value that cannot be weak-referenced.

bind_attribute(name: str, value: object, *, weak_ref: bool | None = None) → None

Store one attribute/value binding by name.

Contract:

Delegates to the shared _bind(...) helper using the attributes store and the requested reference mode.

Parameters:

• name -- Binding name.

• value -- Bound attribute/value.

• weak_ref -- Explicit reference-mode override. True forces weak storage, False forces strong storage, and None uses the room-local workstation default.

Returns:

None.

Raises:

• ValueError -- If name is empty.

• TypeError -- If weak storage is requested for a value that cannot be weak-referenced.

bind_method(name: str, value: object, *, weak_ref: bool | None = None) → None

Store one method/callable binding by name.

Contract:

Delegates to the shared _bind(...) helper using the methods store and the requested reference mode.

Parameters:

• name -- Binding name.

• value -- Bound method/callable.

• weak_ref -- Explicit reference-mode override. True forces weak storage, False forces strong storage, and None uses the room-local workstation default.

Returns:

None.

Raises:

• ValueError -- If name is empty.

• TypeError -- If weak storage is requested for a value that cannot be weak-referenced.

get(name: str, *, store: str | None = None) → object

Return one saved binding by name.

Parameters:

• name -- Binding name to resolve.

• store -- Optional explicit store name (objects, attributes, methods). When omitted, the binding must resolve uniquely across the logical stores.

Returns:

Saved binding value.

Return type:

object

Raises:

ValueError -- If name is empty, the binding is missing, or the name is ambiguous across the logical stores.

release(name: str, *, store: str | None = None) → object

Remove one saved binding and return the removed value.

Parameters:

• name -- Binding name to remove.

• store -- Optional explicit store name. When omitted, the binding must resolve uniquely across the logical stores.

Returns:

Removed binding value.

Return type:

object

Raises:

ValueError -- If the binding cannot be resolved.

describe_bindings() → Dict[str, List[str]]

Return a detached summary of saved binding names by logical store.

Contract:

• Returns a FIVE-KEY summary - objects, attributes, methods, target_name and target_store - always with all five keys present, so callers can index them without a get.

• target_name and target_store are normalized to LISTS for shape consistency with the other three: empty when no target is bound, single-element when one is. Neither is a list of many targets. target_store names WHICH store the active target came from, so a caller can round-trip it back through get(name, store=...).

• Names only, not values: this describes what is bound, not what those bindings currently hold.

Threading:

Reads under self._lock, so the result is a coherent snapshot.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the object has been cleaned.

Returns:

Binding names grouped by logical store.

Return type:

Dict[str, List[str]]

set_target(name: str, *, store: str | None = None) → None

Select one saved binding as the active target.

Parameters:

• name -- Binding name to select.

• store -- Optional explicit store name. When omitted, the binding must resolve uniquely across the logical stores.

Returns:

None.

Raises:

ValueError -- If the binding cannot be resolved.

get_target() → object

Return the currently selected target value.

Returns:

Current target value.

Return type:

object

Raises:

ValueError -- If no target is selected.

clear_target() → None

Clear the current active-target selection only.

Contract:

• Leaves all stored bindings intact.

• Resets only the active-target pointers.

Returns:

None.

cleanup_target(*method_names: str) → None

Call cleanup methods on the current target and then clear target selection.

Parameters:

*method_names -- Optional ordered cleanup method names. When omitted, the workstation uses the default sequence: cleanup, close, dispose.

Returns:

None.

Raises:

• ValueError -- If no target is selected, a method name is empty, or no cleanup method can be resolved on the current target.

• RuntimeError -- If one resolved cleanup method is not callable.

call_target(*args: Any, bind_as_name: str | None = None, bind_as_store: str = 'objects', **kwargs: Any) → object

Invoke the current target and optionally bind the return value.

Contract:

• Resolves the current target through the logical store layer.

• When bind_as_name is supplied, the return value is rebound through the normal workstation bind path with weak_ref=None, which means the room default applies.

Parameters:

• *args -- Positional arguments passed to the target.

• bind_as_name -- Optional workstation binding name for the return value.

• bind_as_store -- Store to use when binding the return value: objects, attributes, or methods.

• **kwargs -- Keyword arguments passed to the target.

Returns:

Target return value.

Return type:

object

Raises:

• ValueError -- If no target is selected or bind_as_store is invalid.

• RuntimeError -- If the target is not callable.

Topic reference · Full contents