terminator_dbus ¤

def get_ancestors(self, node_id: str) -> list[dict[str, Any]]:
    """Return parents from the nearest split or tab through the window."""
    ancestors = []
    parent = self.get_parent(node_id)
    while parent is not None:
        ancestors.append(parent)
        parent = self.get_parent(parent["id"])
    return ancestors

def get_children(self, node_id: str) -> list[dict[str, Any]]:
    """Return children in tab order, left/right order, or above/below order."""
    return [self.get_node(child) for child in self.get_node(node_id)["children"]]

def get_neighbors(self, uuid: str, direction: str) -> list[dict[str, Any]]:
    """Return all terminals sharing the requested edge in the same tab.

    Directions are `right`, `left`, `above`, and `below`. Results follow
    display order along the shared edge. There is no wrapping at tab edges.
    Rectangles use normalized tab coordinates and ignore separator widths.

    Raises:
        KeyError: The UUID is absent from the snapshot.
        ValueError: The node is not a terminal, or the direction is invalid.
    """
    if direction not in {"right", "left", "above", "below"}:
        raise ValueError(f"Unknown neighbor direction: {direction}")
    source = self.get_node(uuid)
    if source["type"] != "terminal":
        raise ValueError("Neighbors require a terminal UUID")
    x, y, width, height = source["rect"]
    matches = []
    for node in self.nodes.values():
        if node["type"] != "terminal" or node["tab"] != source["tab"] or node["id"] == uuid:
            continue
        nx, ny, nw, nh = node["rect"]
        if direction in {"left", "right"}:
            edge = nx + nw if direction == "left" else nx
            source_edge = x if direction == "left" else x + width
            overlap = min(y + height, ny + nh) - max(y, ny)
            order = ny
        else:
            edge = ny + nh if direction == "above" else ny
            source_edge = y if direction == "above" else y + height
            overlap = min(x + width, nx + nw) - max(x, nx)
            order = nx
        if overlap > _EPSILON and math.isclose(edge, source_edge, abs_tol=_EPSILON):
            matches.append((order, node))
    return [node for _, node in sorted(matches, key=lambda item: item[0])]

def get_node(self, node_id: str) -> dict[str, Any]:
    """Return a node record; raise `KeyError` if the ID is absent."""
    return self.nodes[node_id]

def get_parent(self, node_id: str) -> dict[str, Any] | None:
    """Return a node's parent, or `None` for the window root."""
    parent = self.get_node(node_id)["parent"]
    return None if parent is None else self.get_node(parent)

def get_sibling(self, node_id: str) -> dict[str, Any] | None:
    """Return the other branch of a split, or `None` outside a split."""
    parent = self.get_parent(node_id)
    if parent is None or parent["type"] != "split":
        return None
    return next(child for child in self.get_children(parent["id"]) if child["id"] != node_id)

def focus(self, uuid: str) -> None:
    """Select a terminal's tab and focus its window and shell."""
    self._call("focus", uuid, signature="s")

def get_ancestors(self, node_id: str) -> list[dict[str, Any]]:
    """Inspect current ancestors from the nearest parent through the window."""
    return self._query("get_ancestors", node_id)

def get_children(self, node_id: str) -> list[dict[str, Any]]:
    """Inspect current children in display order."""
    return self._query("get_children", node_id)

def get_neighbors(self, uuid: str, direction: str) -> list[dict[str, Any]]:
    """Inspect all terminals sharing the requested edge in the current tab."""
    return self._query("get_neighbors", uuid, direction, signature="ss")

def get_node(self, node_id: str) -> dict[str, Any]:
    """Inspect a node in the current layout."""
    return self._query("get_node", node_id)

def get_parent(self, node_id: str) -> dict[str, Any] | None:
    """Inspect the current parent, or return `None` for a window root."""
    return self._query("get_parent", node_id)

def get_sibling(self, node_id: str) -> dict[str, Any] | None:
    """Inspect the other branch of the current parent split, if any."""
    return self._query("get_sibling", node_id)

def get_tree(self, uuid: str) -> _LayoutTree:
    """Return a local layout snapshot for the window containing this node."""
    return _LayoutTree(self._query("get_tree", uuid))

def move_node(self, node_id: str, target_id: str, direction: str) -> str:
    """Move a terminal or subtree beside another node without restarting shells.

    Nodes may belong to different tabs or windows. The returned ID denotes
    the new split enclosing the target and moved node. Empty source splits,
    tabs, and windows are removed. Moving into one's own subtree is invalid.
    """
    return str(self._call("move_node", node_id, target_id, direction, signature="sss"))

def new_tab(self, uuid: str, options: Mapping[str, str] | None = None) -> str:
    """Create a tab with optional `command` and `directory` settings."""
    return str(self._call("new_tab", uuid, dict(options or {}), signature="sa{ss}"))

def rotate_subtree(self, node_id: str, direction: str = "clockwise") -> str:
    """Rotate a split `clockwise` or `counterclockwise`, preserving node IDs."""
    return str(self._call("rotate_subtree", node_id, direction, signature="ss"))

def set_split_ratio(self, node_id: str, ratio: float) -> None:
    """Set the first branch's share of space, strictly between zero and one."""
    self._call("set_split_ratio", node_id, ratio, signature="sd")

def split(self, uuid: str, direction: str, options: Mapping[str, str] | None = None) -> str:
    """Create a terminal `right`, `left`, `above`, or `below` the source."""
    return str(self._call("split", uuid, direction, dict(options or {}), signature="ssa{ss}"))

def split_node(self, node_id: str, direction: str, options: Mapping[str, str] | None = None) -> str:
    """Add a terminal beside an existing terminal or entire split subtree.

    Omitted launch options inherit from the subtree's first terminal in
    display order, subject to Terminator's profile inheritance setting.
    """
    return str(self._call("split_node", node_id, direction, dict(options or {}), signature="ssa{ss}"))

def swap_children(self, node_id: str) -> None:
    """Exchange both branches while keeping the split's divider ratio."""
    self._call("swap_children", node_id, signature="s")

def bg_img(self, uuid: str, options: Mapping[str, str]) -> None:
    """Set the background image of one terminal.

    Parameters:
        uuid: Target terminal UUID.
        options: Mapping with the image path in the `file` key.
    """
    self._call("bg_img", uuid, _options(options), signature="vv")

def bg_img_all(self, options: Mapping[str, str]) -> None:
    """Set the background image of all terminals.

    Parameters:
        options: Mapping with the image path in the `file` key.
    """
    self._call("bg_img_all", _options(options), signature="v")

def call(
    self,
    method_name: str,
    *args: object,
    interface: str | None = None,
    object_path: str = BUS_PATH,
    signature: str | None = None,
) -> Any:
    """Call an arbitrary method on Terminator or a plugin's D-Bus interface.

    Parameters:
        method_name: D-Bus method to call.
        *args: Positional arguments sent to the method.
        interface: D-Bus interface name. Defaults to Terminator's built-in interface.
        object_path: D-Bus object path exported by the selected Terminator service.
        signature: Input signature. When unset, the proxy uses introspection
            to find the signature. An empty string declares a method with no inputs.

    Returns:
        The original D-Bus result. Plugin results are not converted or
        checked for error strings.

    Raises:
        dbus.DBusException: The object, interface, or method is unavailable,
            or the remote method raises an exception.
        TerminatorError: A built-in terminal creation method returned an
            `ERROR:` response.
    """
    interface_name = self.bus_name if interface is None else interface
    builtin = object_path == BUS_PATH and interface_name == self.bus_name
    if builtin and signature is not None:
        target = self._interface
    else:
        target = self.get_interface(interface_name, object_path=object_path, introspect=signature is None)
    method = target.get_dbus_method(method_name)
    result = method(*args, signature=signature)
    if (
        builtin
        and method_name in {"new_window", "new_tab", "hsplit", "vsplit"}
        and isinstance(result, str)
        and result.startswith("ERROR:")
    ):
        raise TerminatorError(method_name, result)
    return result

def discover_interfaces(
    self,
    object_path: str = "/",
    *,
    recursive: bool = True,
) -> dict[str, dict[str, dbus.Interface]]:
    """Discover exported D-Bus interfaces and create their dynamic proxies.

    Discovery reports interfaces exported by the running Terminator
    process. It does not list installed or disabled Python plugins.
    Standard D-Bus and built-in Terminator interfaces are included.

    Parameters:
        object_path: Object path where discovery starts. The root path
            finds plugin objects anywhere in the selected service.
        recursive: Follow child objects described by introspection.

    Returns:
        Object paths mapped to interface names and their dynamic proxies.
        Nodes with no interfaces are omitted.

    Raises:
        dbus.DBusException: An object cannot be introspected, or the
            Terminator service is unavailable.
        xml.etree.ElementTree.ParseError: An object returns invalid XML.
    """
    discovered: dict[str, dict[str, dbus.Interface]] = {}
    pending: list[tuple[str, ET.Element | None]] = [(object_path, None)]
    visited: set[str] = set()
    while pending:
        path, node = pending.pop()
        if path in visited:
            continue
        visited.add(path)
        if node is None:
            description = self.call(
                "Introspect",
                interface="org.freedesktop.DBus.Introspectable",
                object_path=path,
                signature="",
            )
            # The selected Terminator process supplies the introspection XML.
            node = ET.fromstring(str(description))  # noqa: S314
        interfaces = {
            element.attrib["name"]: self.get_interface(element.attrib["name"], object_path=path)
            for element in node.findall("interface")
        }
        if interfaces:
            discovered[path] = interfaces
        if recursive:
            for child in reversed(node.findall("node")):
                child_path = f"{path.rstrip('/')}/{child.attrib['name']}"
                # A child with contents includes its full introspection description.
                pending.append((child_path, child if len(child) else None))
    return discovered

def get_focused_terminal(self) -> str | None:
    """Return the focused terminal UUID, if a terminal has focus."""
    return _optional_string(self._call("get_focused_terminal", signature=""))

def get_interface(self, interface: str, *, object_path: str = BUS_PATH, introspect: bool = True) -> dbus.Interface:
    """Create a dynamic proxy for an interface exported by Terminator or a plugin.

    Methods are available as attributes on the returned interface. For
    example, a plugin that exports `new_tab` can be called with
    `plugin.new_tab(uuid, command)`. These calls return raw D-Bus results.

    Parameters:
        interface: D-Bus interface name.
        object_path: D-Bus object path exported by the selected Terminator service.
        introspect: Use introspection to find method signatures. Disable
            this when every call supplies its own signature.

    Returns:
        A `dbus.Interface` using the client's existing bus connection.
        Proxies for the same path and introspection setting are reused.

    Raises:
        dbus.DBusException: The Terminator service is unavailable.
    """
    key = object_path, introspect
    if key not in self._proxies:
        self._proxies[key] = self._bus.get_object(self.bus_name, object_path, introspect=introspect)
    return dbus.Interface(self._proxies[key], interface)

def get_tab(self, uuid: str) -> str | None:
    """Return the parent tab identifier of a terminal.

    Terminator does not assign UUIDs to tabs. It currently returns an
    empty string for a terminal in a notebook and no value otherwise.

    Parameters:
        uuid: Target terminal UUID.
    """
    return _optional_string(self._call("get_tab", uuid, signature="v"))

def get_tab_title(self, uuid: str) -> str | None:
    """Return the parent tab title of a terminal, if it has one.

    Parameters:
        uuid: Target terminal UUID.
    """
    return _optional_string(self._call("get_tab_title", uuid, signature="v"))

def get_terminals(self) -> list[str]:
    """Return the UUID of every terminal."""
    return [str(uuid) for uuid in self._call("get_terminals", signature="")]

def get_window(self, uuid: str) -> str:
    """Return the parent window UUID of a terminal.

    Parameters:
        uuid: Target terminal UUID.
    """
    return str(self._call("get_window", uuid, signature="v"))

def get_window_title(self, uuid: str) -> str:
    """Return the parent window title of a terminal.

    Parameters:
        uuid: Target terminal UUID.
    """
    return str(self._call("get_window_title", uuid, signature="v"))

def hsplit(self, uuid: str, options: Mapping[str, str] | None = None) -> str:
    """Split a terminal horizontally and return the new terminal UUID.

    Parameters:
        uuid: Target terminal UUID.
        options: Optional `execute` command and `title` for the new
            terminal.

    Returns:
        The new terminal UUID.

    Raises:
        TerminatorError: Terminator returned an `ERROR:` response.
    """
    return str(self._call("hsplit", uuid, _options(options), signature="vv"))

def new_tab(self, uuid: str) -> str:
    """Create a tab beside a terminal and return the new terminal UUID.

    Parameters:
        uuid: UUID of a terminal in the target window.

    Returns:
        The new terminal UUID.

    Raises:
        TerminatorError: Terminator returned an `ERROR:` response.
    """
    return str(self._call("new_tab", uuid, signature="v"))

def new_tab_cmdline(self, options: Mapping[str, str]) -> None:
    """Create a tab from serialized Terminator command-line options.

    Parameters:
        options: Complete option mapping produced by Terminator's command
            line parser. Keys and values must be strings.
    """
    self._call("new_tab_cmdline", _options(options), signature="a{ss}")

def new_window(self) -> str:
    """Create a window and return its first terminal UUID.

    Raises:
        TerminatorError: Terminator returned an `ERROR:` response.
    """
    return str(self._call("new_window", signature=""))

def new_window_cmdline(self, options: Mapping[str, str]) -> None:
    """Create a window from serialized Terminator command-line options.

    Parameters:
        options: Complete option mapping produced by Terminator's command
            line parser. Keys and values must be strings.
    """
    self._call("new_window_cmdline", _options(options), signature="a{ss}")

def reload_configuration(self) -> None:
    """Reload the configuration of all terminals."""
    self._call("reload_configuration", signature="")

def set_tab_title(self, uuid: str, options: Mapping[str, str]) -> None:
    """Set a terminal's parent tab title.

    Parameters:
        uuid: Target terminal UUID.
        options: Mapping with the new title in the `tab-title` key.
    """
    self._call("set_tab_title", uuid, _options(options), signature="vv")

def switch_profile(self, uuid: str, options: Mapping[str, str]) -> None:
    """Switch one terminal to a profile.

    Parameters:
        uuid: Target terminal UUID.
        options: Mapping with the profile name in the `profile` key.
    """
    self._call("switch_profile", uuid, _options(options), signature="vv")

def switch_profile_all(self, options: Mapping[str, str]) -> None:
    """Switch all terminals to a profile.

    Parameters:
        options: Mapping with the profile name in the `profile` key.
    """
    self._call("switch_profile_all", _options(options), signature="v")

def toggle_visibility_cmdline(self, options: Mapping[str, str]) -> None:
    """Toggle the visibility of every Terminator window.

    Parameters:
        options: Serialized command-line options. Terminator currently
            ignores the values.
    """
    self._call("toggle_visibility_cmdline", _options(options), signature="a{ss}")

def unhide_cmdline(self, options: Mapping[str, str]) -> None:
    """Show every hidden Terminator window.

    Parameters:
        options: Serialized command-line options. Terminator currently
            ignores the values.
    """
    self._call("unhide_cmdline", _options(options), signature="a{ss}")

def vsplit(self, uuid: str, options: Mapping[str, str] | None = None) -> str:
    """Split a terminal vertically and return the new terminal UUID.

    Parameters:
        uuid: Target terminal UUID.
        options: Optional `execute` command and `title` for the new
            terminal.

    Returns:
        The new terminal UUID.

    Raises:
        TerminatorError: Terminator returned an `ERROR:` response.
    """
    return str(self._call("vsplit", uuid, _options(options), signature="vv"))