Builder protocol - `tmuxp.workspace.builder.protocol`¶

Public contract for tmuxp workspace builders.

A workspace builder turns an expanded workspace dict into a live tmux session. tmuxp.workspace.builder.classic.ClassicWorkspaceBuilder is the default implementation; third parties may ship their own and select them with the workspace_builder config key (see tmuxp.workspace.builder.registry).

This module is intentionally dependency-light (typing only) so builder authors can import the contract without pulling in tmuxp’s resolution machinery.

The contract is synchronous today. Async builders are an additive future extension: a subclass protocol can declare an async build entry point and a capability flag, discovered through the same entry-point group, without changing this sync surface.

class tmuxp.workspace.builder.protocol.WorkspaceBuilderProtocol ¶ class[source] class[source] class tmuxp.workspace.builder.protocol.WorkspaceBuilderProtocol ¶

Bases: Protocol

Contract a builder must satisfy to be driven by tmuxp load.

A conforming builder is constructed with at least session_config and server (plus the optional plugins and on_* callbacks the classic builder accepts). It exposes build(), surfaces the populated tmux session via session, and honors the plugin/progress integration points the CLI drives.

Because the protocol carries data members (session, plugins, the on_* callbacks), validate instances with isinstance(); class-level issubclass checks are not supported for runtime-checkable protocols with non-method members.

Examples

A builder implementing the full contract satisfies the protocol:

>>> from tmuxp.workspace.builder.protocol import WorkspaceBuilderProtocol
>>> class MiniBuilder:
...     plugins: list = []
...     on_progress = None
...     on_before_script = None
...     on_script_output = None
...     on_build_event = None
...     def __init__(self, session_config, server, **kwargs):
...         self._session_config = session_config
...     def build(self, session=None, append=False):
...         ...
...     def session_exists(self, session_name):
...         ...
...     def find_current_attached_session(self):
...         ...
...     @property
...     def session(self):
...         ...
>>> builder = MiniBuilder(session_config={}, server=None)
>>> isinstance(builder, WorkspaceBuilderProtocol)
True

An object missing the contract does not:

>>> isinstance(object(), WorkspaceBuilderProtocol)
False

__init__(session_config, server, plugins=None, on_progress=None, on_before_script=None, on_script_output=None, on_build_event=None) ¶ method[source] method[source] __init__(session_config, server, plugins=None, on_progress=None, on_before_script=None, on_script_output=None, on_build_event=None) ¶

Construct a builder from an expanded workspace and a tmux server.

Parameters:

session_config (dict[str, Any])
server (Server)
plugins (list[Any] | None)
on_progress (Callable[[str], None] | None)
on_before_script (Callable[[], None] | None)
on_script_output (Callable[[str], None] | None)
on_build_event (Callable[[dict[str, Any]], None] | None)

Return type:

None

Builder protocol - tmuxp.workspace.builder.protocol¶

Builder protocol - `tmuxp.workspace.builder.protocol`¶