terminator-dbus 0.1.0__py3-none-any.whl

terminator_dbus/__init__.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: ISC
+#
+# ISC License
+#
+# Copyright (c) 2026, Timothée Mazzucotelli and contributors
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+"""Terminator D-Bus package.
+
+Python library to interact with Terminator through D-Bus.
+"""
+
+from __future__ import annotations
+
+from terminator_dbus._internal.cli import get_parser, main
+from terminator_dbus._internal.client import BUS_BASE, BUS_PATH, Terminator, get_bus_name
+
+__all__: list[str] = ["BUS_BASE", "BUS_PATH", "Terminator", "get_bus_name", "get_parser", "main"]

terminator_dbus/__main__.py

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: ISC
+#
+# ISC License
+#
+# Copyright (c) 2026, Timothée Mazzucotelli and contributors
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+"""Entry-point module, in case you use `python -m terminator_dbus`.
+
+Why does this file exist, and why `__main__`? For more info, read:
+
+- https://www.python.org/dev/peps/pep-0338/
+- https://docs.python.org/3/using/cmdline.html#cmdoption-m
+"""
+
+import sys
+
+from terminator_dbus._internal.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

terminator_dbus/_internal/__init__.py

@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: ISC
+#
+# ISC License
+#
+# Copyright (c) 2026, Timothée Mazzucotelli and contributors
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

terminator_dbus/_internal/cli.py

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: ISC
+#
+# ISC License
+#
+# Copyright (c) 2026, Timothée Mazzucotelli and contributors
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+# Why does this file exist, and why not put this in `__main__`?
+#
+# You might be tempted to import things from `__main__` later,
+# but that will cause problems: the code will get executed twice:
+#
+# - When you run `python -m terminator_dbus` python will execute
+#   `__main__.py` as a script. That means there won't be any
+#   `terminator_dbus.__main__` in `sys.modules`.
+# - When you import `__main__` it will get executed again (as a module) because
+#   there's no `terminator_dbus.__main__` in `sys.modules`.
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+from terminator_dbus._internal import debug
+
+
+class _DebugInfo(argparse.Action):
+    def __init__(self, nargs: int | str | None = 0, **kwargs: Any) -> None:
+        super().__init__(nargs=nargs, **kwargs)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> None:  # noqa: ARG002
+        debug._print_debug_info()
+        sys.exit(0)
+
+
+def get_parser() -> argparse.ArgumentParser:
+    """Return the CLI argument parser.
+
+    Returns:
+        An argparse parser.
+    """
+    parser = argparse.ArgumentParser(prog="terminator-dbus")
+    parser.add_argument("-V", "--version", action="version", version=f"%(prog)s {debug._get_version()}")
+    parser.add_argument("--debug-info", action=_DebugInfo, help="Print debug information.")
+    return parser
+
+
+def main(args: list[str] | None = None) -> int:
+    """Run the main program.
+
+    This function is executed when you type `terminator-dbus` or `python -m terminator_dbus`.
+
+    Parameters:
+        args: Arguments passed from the command line.
+
+    Returns:
+        An exit code.
+    """
+    parser = get_parser()
+    opts = parser.parse_args(args=args)
+    print(opts)
+    return 0

terminator_dbus/_internal/client.py

@@ -0,0 +1,294 @@
+# SPDX-License-Identifier: ISC
+#
+# ISC License
+#
+# Copyright (c) 2026, Timothée Mazzucotelli and contributors
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+from __future__ import annotations
+
+import hashlib
+import os
+from typing import TYPE_CHECKING, Any, Final
+
+import dbus
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from dbus.bus import BusConnection
+
+
+BUS_BASE: Final = "net.tenshu.Terminator2"
+"""Base name of Terminator's D-Bus service and interface."""
+
+BUS_PATH: Final = "/net/tenshu/Terminator2"
+"""Object path of Terminator's D-Bus service."""
+
+
+def _default_display() -> str | None:
+    backend = os.environ.get("GDK_BACKEND", "").split(",", maxsplit=1)[0]
+    if backend == "wayland":
+        return os.environ.get("WAYLAND_DISPLAY") or os.environ.get("DISPLAY")
+    if backend == "x11":
+        return os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY")
+    if os.environ.get("XDG_SESSION_TYPE") == "wayland":
+        return os.environ.get("WAYLAND_DISPLAY") or os.environ.get("DISPLAY")
+    return os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY")
+
+
+def get_bus_name(display: str | None = None) -> str:
+    """Return the D-Bus service and interface name for a display.
+
+    Terminator appends the MD5 digest of its GDK display name to
+    `net.tenshu.Terminator2`. It removes the screen suffix before it creates
+    the digest. For example, `:0` and `:0.0` use the same D-Bus name.
+
+    Parameters:
+        display: GDK display name. The current desktop display is used when
+            this argument is not set.
+
+    Returns:
+        The display-specific name, or the base name when no display is known.
+    """
+    if display is None:
+        display = _default_display()
+    if not display:
+        return BUS_BASE
+
+    display_without_screen = display.partition(".")[0]
+    display_digest = hashlib.md5(display_without_screen.encode(), usedforsecurity=False).hexdigest()
+    return f"{BUS_BASE}{display_digest}"
+
+
+def _options(values: Mapping[str, str] | None = None) -> dbus.Dictionary:
+    return dbus.Dictionary({} if values is None else values, signature="ss")
+
+
+def _optional_string(value: object) -> str | None:
+    if value is None:
+        return None
+    return str(value)
+
+
+class Terminator:
+    """Provide Python methods for Terminator's complete D-Bus interface.
+
+    The client keeps one session-bus connection and one proxy. It sends known
+    method signatures directly, so `dbus-python` does not need an
+    introspection request before the first method call.
+
+    Parameters:
+        bus: An existing D-Bus connection. A session-bus connection is created
+            when this argument is not set.
+        display: GDK display name used to calculate Terminator's D-Bus name.
+        bus_name: Exact D-Bus service name. Use this argument for a custom or
+            already discovered Terminator service.
+
+    Raises:
+        ValueError: Both `display` and `bus_name` were specified.
+        dbus.DBusException: The session bus or Terminator service is not
+            available.
+    """
+
+    def __init__(
+        self,
+        *,
+        bus: BusConnection | None = None,
+        display: str | None = None,
+        bus_name: str | None = None,
+    ) -> None:
+        if display is not None and bus_name is not None:
+            raise ValueError("display and bus_name cannot both be specified")
+
+        self._bus_name = get_bus_name(display) if bus_name is None else bus_name
+        self._bus = dbus.SessionBus() if bus is None else bus
+        proxy = self._bus.get_object(self.bus_name, BUS_PATH, introspect=False)
+        self._interface = dbus.Interface(proxy, self.bus_name)
+
+    @property
+    def bus_name(self) -> str:
+        """Return the D-Bus service and interface name used by this client."""
+        return self._bus_name
+
+    def _call(self, method_name: str, *args: object, signature: str) -> Any:
+        method = self._interface.get_dbus_method(method_name)
+        return method(*args, signature=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 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 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 new_window(self) -> str:
+        """Create a window and return its first terminal UUID."""
+        return str(self._call("new_window", signature=""))
+
+    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 or an error string from Terminator.
+        """
+        return str(self._call("new_tab", uuid, signature="v"))
+
+    def reload_configuration(self) -> None:
+        """Reload the configuration of all terminals."""
+        self._call("reload_configuration", signature="")
+
+    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 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 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 or an error string from Terminator.
+        """
+        return str(self._call("hsplit", uuid, _options(options), signature="vv"))
+
+    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 or an error string from Terminator.
+        """
+        return str(self._call("vsplit", uuid, _options(options), signature="vv"))
+
+    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_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_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 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 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")

terminator_dbus/_internal/debug.py

@@ -0,0 +1,125 @@
+# SPDX-License-Identifier: ISC
+#
+# ISC License
+#
+# Copyright (c) 2026, Timothée Mazzucotelli and contributors
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+from __future__ import annotations
+
+import os
+import platform
+import sys
+from dataclasses import dataclass
+from importlib import metadata
+
+
+@dataclass
+class _Variable:
+    """Dataclass describing an environment variable."""
+
+    name: str
+    """Variable name."""
+    value: str
+    """Variable value."""
+
+
+@dataclass
+class _Package:
+    """Dataclass describing a Python package."""
+
+    name: str
+    """Package name."""
+    version: str
+    """Package version."""
+
+
+@dataclass
+class _Environment:
+    """Dataclass to store environment information."""
+
+    interpreter_name: str
+    """Python interpreter name."""
+    interpreter_version: str
+    """Python interpreter version."""
+    interpreter_path: str
+    """Path to Python executable."""
+    platform: str
+    """Operating System."""
+    packages: list[_Package]
+    """Installed packages."""
+    variables: list[_Variable]
+    """Environment variables."""
+
+
+def _interpreter_name_version() -> tuple[str, str]:
+    if hasattr(sys, "implementation"):
+        impl = sys.implementation.version
+        version = f"{impl.major}.{impl.minor}.{impl.micro}"
+        kind = impl.releaselevel
+        if kind != "final":
+            version += kind[0] + str(impl.serial)
+        return sys.implementation.name, version
+    return "", "0.0.0"
+
+
+def _get_version(dist: str = "terminator-dbus") -> str:
+    """Get version of the given distribution.
+
+    Parameters:
+        dist: A distribution name.
+
+    Returns:
+        A version number.
+    """
+    try:
+        return metadata.version(dist)
+    except metadata.PackageNotFoundError:
+        return "0.0.0"
+
+
+def _get_debug_info() -> _Environment:
+    """Get debug/environment information.
+
+    Returns:
+        Environment information.
+    """
+    py_name, py_version = _interpreter_name_version()
+    packages = ["terminator-dbus"]
+    variables = ["PYTHONPATH", *[var for var in os.environ if var.startswith("TERMINATOR_DBUS")]]
+    return _Environment(
+        interpreter_name=py_name,
+        interpreter_version=py_version,
+        interpreter_path=sys.executable,
+        platform=platform.platform(),
+        variables=[_Variable(var, val) for var in variables if (val := os.getenv(var))],
+        packages=[_Package(pkg, _get_version(pkg)) for pkg in packages],
+    )
+
+
+def _print_debug_info() -> None:
+    """Print debug/environment information."""
+    info = _get_debug_info()
+    print(f"- __System__: {info.platform}")
+    print(f"- __Python__: {info.interpreter_name} {info.interpreter_version} ({info.interpreter_path})")
+    print("- __Environment variables__:")
+    for var in info.variables:
+        print(f"  - `{var.name}`: `{var.value}`")
+    print("- __Installed packages__:")
+    for pkg in info.packages:
+        print(f"  - `{pkg.name}` v{pkg.version}")
+
+
+if __name__ == "__main__":
+    _print_debug_info()

terminator_dbus-0.1.0.dist-info/METADATA

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: terminator-dbus
+Version: 0.1.0
+Summary: Python library to interact with Terminator through D-Bus.
+Author-Email: =?utf-8?q?Timoth=C3=A9e_Mazzucotelli?= <dev@pawamoy.fr>
+License-Expression: ISC
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Project-URL: Homepage, https://pawamoy.github.io/terminator-dbus
+Project-URL: Documentation, https://pawamoy.github.io/terminator-dbus
+Project-URL: Changelog, https://pawamoy.github.io/terminator-dbus/changelog
+Project-URL: Repository, https://github.com/pawamoy/terminator-dbus
+Project-URL: Issues, https://github.com/pawamoy/terminator-dbus/issues
+Project-URL: Discussions, https://github.com/pawamoy/terminator-dbus/discussions
+Project-URL: Gitter, https://gitter.im/terminator-dbus/community
+Project-URL: Funding, https://github.com/sponsors/pawamoy
+Requires-Python: >=3.10
+Requires-Dist: dbus-python>=1.3.2
+Description-Content-Type: text/markdown
+
+# Terminator D-Bus
+
+
+[![ci](https://github.com/pawamoy/terminator-dbus/workflows/ci/badge.svg)](https://github.com/pawamoy/terminator-dbus/actions?query=workflow%3Aci)
+[![documentation](https://img.shields.io/badge/docs-zensical-FF9100.svg?style=flat)](https://pawamoy.github.io/terminator-dbus/)
+[![pypi version](https://img.shields.io/pypi/v/terminator-dbus.svg)](https://pypi.org/project/terminator-dbus/)
+[![gitter](https://img.shields.io/badge/matrix-chat-4DB798.svg?style=flat)](https://app.gitter.im/#/room/#terminator-dbus:gitter.im)
+
+
+Python library to interact with Terminator through D-Bus.
+
+
+## Installation
+
+
+```bash
+pip install terminator-dbus
+```
+
+
+With [`uv`](https://docs.astral.sh/uv/):
+
+
+```bash
+uv tool install terminator-dbus
+```
+
+
+`dbus-python` needs the D-Bus development files when no system package or wheel is available.
+
+
+## Usage
+
+
+Create one client and reuse it for all calls:
+
+
+```python
+from terminator_dbus import Terminator
+
+terminator = Terminator()
+terminal = terminator.get_focused_terminal()
+
+if terminal is not None:
+    new_terminal = terminator.vsplit(
+        terminal,
+        {"execute": "htop", "title": "Processes"},
+    )
+    terminator.switch_profile(new_terminal, {"profile": "work"})
+```
+
+
+The client uses the current X11 or Wayland display by default. Pass `display` if the current environment does not identify the correct display:
+
+
+```python
+terminator = Terminator(display=":1")
+```
+
+
+Pass `bus_name` when you already know the complete D-Bus service name:
+
+
+```python
+terminator = Terminator(bus_name="net.tenshu.Terminator2...")
+```
+
+
+`dbus.DBusException` reports connection and remote method failures. Terminator itself returns strings that start with `ERROR:` for some tab and split failures.
+
+
+## D-Bus interface
+
+
+This package follows the interface in [Terminator 2.1.6 `ipc.py`](https://github.com/gnome-terminator/terminator/blob/v2.1.6/terminatorlib/ipc.py).
+
+
+- Base service and interface name: `net.tenshu.Terminator2`
+- Object path: `/net/tenshu/Terminator2`
+- Display-specific name: the base name followed by the MD5 digest of the GDK display name
+
+
+Terminator removes the screen suffix before it creates the digest. Thus, `:0` and `:0.0` use the same service name.
+
+
+The `Terminator` class exposes every method in the service:
+
+
+| Python method | D-Bus input | Purpose | Result |
+| --- | --- | --- | --- |
+| `new_window_cmdline(options)` | `a{ss}` | Create a window from serialized command-line options. | `None` |
+| `new_tab_cmdline(options)` | `a{ss}` | Create a tab from serialized command-line options. | `None` |
+| `toggle_visibility_cmdline(options)` | `a{ss}` | Toggle all window visibility. | `None` |
+| `unhide_cmdline(options)` | `a{ss}` | Show all hidden windows. | `None` |
+| `new_window()` | empty | Create a window. | New terminal UUID or error string |
+| `new_tab(uuid)` | `v` | Create a tab in a terminal's window. | New terminal UUID or error string |
+| `reload_configuration()` | empty | Reload configuration for all terminals. | `None` |
+| `bg_img_all(options)` | `v` | Set all background images from the `file` option. | `None` |
+| `bg_img(uuid, options)` | `vv` | Set one background image from the `file` option. | `None` |
+| `hsplit(uuid, options=None)` | `vv` | Split a terminal horizontally. | New terminal UUID or error string |
+| `vsplit(uuid, options=None)` | `vv` | Split a terminal vertically. | New terminal UUID or error string |
+| `get_terminals()` | empty | Get all terminal UUIDs. | `list[str]` |
+| `get_focused_terminal()` | empty | Get the focused terminal UUID. | `str \| None` |
+| `get_window(uuid)` | `v` | Get a terminal's window UUID. | `str` |
+| `get_window_title(uuid)` | `v` | Get a terminal's window title. | `str` |
+| `get_tab(uuid)` | `v` | Get a terminal's tab identifier. | `str \| None` |
+| `get_tab_title(uuid)` | `v` | Get a terminal's tab title. | `str \| None` |
+| `set_tab_title(uuid, options)` | `vv` | Set a tab title from the `tab-title` option. | `None` |
+| `switch_profile(uuid, options)` | `vv` | Set one profile from the `profile` option. | `None` |
+| `switch_profile_all(options)` | `v` | Set all profiles from the `profile` option. | `None` |
+
+
+Terminator does not assign identifiers to tabs. Its `get_tab` method returns an empty string for a terminal in a notebook.
+
+
+The four `*_cmdline` methods require string-to-string dictionaries. The window and tab creation methods require the complete option mapping from Terminator's command-line parser.
+
+
+Terminator does not declare D-Bus output signatures. `dbus-python` infers each output signature from the value returned by the service method.
+
+
+## Sponsors
+
+
+<!-- sponsors-start -->
+<!-- sponsors-end -->

terminator_dbus-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+terminator_dbus-0.1.0.dist-info/METADATA,sha256=ZIBNR-ltKtm_viLdTwCF40e7AUcgijgMMFdEpfFFbW8,6207
+terminator_dbus-0.1.0.dist-info/WHEEL,sha256=Y8xFLOH-FrS4gLE6ON4ti06sl2W_9QUDiRaTK3tfwig,91
+terminator_dbus-0.1.0.dist-info/entry_points.txt,sha256=DZGbTVz8MoUuz56ejS6uA5L40r5cNGLW3XVgifiQx8A,73
+terminator_dbus-0.1.0.dist-info/licenses/LICENSE,sha256=I3KB1-ErGw-w8Lv5cPRgpAQKNKPv_CpOJvpYunP93-E,771
+terminator_dbus/__init__.py,sha256=2__lOnprDspKWl2Wmx0MCBjZDNFoDO8BpM6rJ69dZGM,1209
+terminator_dbus/__main__.py,sha256=QXkwKNVavUPbXObqIR3r29pvZ3xDdDMGeeJTFej11cQ,1197
+terminator_dbus/_internal/__init__.py,sha256=LH7HQJydqOYIxZva6Nc0p5zeUpQAxcvUyEwiajkZkdQ,831
+terminator_dbus/_internal/cli.py,sha256=4vW6wRTVncUcHsTsjErEAmFi-FcjytOmGhDO8DnWjBA,2563
+terminator_dbus/_internal/client.py,sha256=SgBYyGQnXoR64Yws_Etv4wbtTbnHLtrgM7N9FLQYb-c,11016
+terminator_dbus/_internal/debug.py,sha256=xrgL0cQWdtOrxh8lFYhwQPTRW-Wfe0Y-YOzE4-d3YZE,3665
+terminator_dbus/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+terminator_dbus-0.1.0.dist-info/RECORD,,

terminator_dbus-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: pdm-backend (2.4.10)
+Root-Is-Purelib: true
+Tag: py3-none-any

terminator_dbus-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+terminator-dbus = terminator_dbus:main
+
+[gui_scripts]
+

terminator_dbus-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, Timothée Mazzucotelli and contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.