tmuxp.workspace.builder.ClassicWorkspaceBuilder

Python

Python
Ruby Unavailable
Lua Unavailable
TypeScript Unavailable
Rust Unavailable
Go Unavailable
Java Unavailable
.NET Unavailable
C++ Unavailable
Swift Unavailable

class tmuxp.workspace.builder.ClassicWorkspaceBuilder class [source] ¶ class [source] ¶ class tmuxp.workspace.builder.ClassicWorkspaceBuilder

Load workspace from workspace dict object.

Build tmux workspace from a configuration. Creates and names windows, sets options, splits windows into panes.

Examples

>>> import yaml

>>> session_config = yaml.load('''
...     session_name: sample workspace
...     start_directory: '~'
...     windows:
...     - window_name: editor
...       layout: main-vertical
...       panes:
...       - shell_command:
...         - cmd: vim
...       - shell_command:
...         - cmd: echo "hey"
...
...     - window_name: logging
...       panes:
...       - shell_command:
...         - cmd: tail | echo 'hi'
...
...     - window_name: test
...       panes:
...       - shell_command:
...         - cmd: htop
... ''', Loader=yaml.Loader)

>>> builder = ClassicWorkspaceBuilder(session_config=session_config, server=server)

New session:

>>> builder.build()

>>> new_session = builder.session

>>> new_session.name == 'sample workspace'
True

>>> len(new_session.windows)
3

>>> sorted([window.name for window in new_session.windows])
['editor', 'logging', 'test']

Existing session:

>>> len(session.windows)
1

>>> builder.build(session=session)

_Caveat:_ Preserves old session name:

>>> session.name == 'sample workspace'
False

>>> len(session.windows)
3

>>> sorted([window.name for window in session.windows])
['editor', 'logging', 'test']

Progress callback:

>>> calls: list[str] = []
>>> progress_cfg = {
...     "session_name": "progress-demo",
...     "windows": [{"window_name": "main", "panes": [{"shell_command": []}]}],
... }
>>> builder = ClassicWorkspaceBuilder(
...     session_config=progress_cfg,
...     server=server,
...     on_progress=calls.append,
... )
>>> builder.build()
>>> "Workspace built" in calls
True

Before-script hook:

>>> hook_calls: list[bool] = []
>>> no_script_cfg = {
...     "session_name": "hook-demo",
...     "windows": [{"window_name": "main", "panes": [{"shell_command": []}]}],
... }
>>> builder = ClassicWorkspaceBuilder(
...     session_config=no_script_cfg,
...     server=server,
...     on_before_script=lambda: hook_calls.append(True),
... )
>>> builder.build()
>>> hook_calls  # no before_script in config, callback not fired
[]

Script output hook:

>>> script_lines: list[str] = []
>>> no_script_cfg2 = {
...     "session_name": "script-output-demo",
...     "windows": [{"window_name": "main", "panes": [{"shell_command": []}]}],
... }
>>> builder = ClassicWorkspaceBuilder(
...     session_config=no_script_cfg2,
...     server=server,
...     on_script_output=script_lines.append,
... )
>>> builder.build()
>>> script_lines  # no before_script in config, callback not fired
[]

Build events hook:

>>> events: list[dict] = []
>>> event_cfg = {
...     "session_name": "events-demo",
...     "windows": [{"window_name": "main", "panes": [{"shell_command": []}]}],
... }
>>> builder = ClassicWorkspaceBuilder(
...     session_config=event_cfg,
...     server=server,
...     on_build_event=events.append,
... )
>>> builder.build()
>>> [e["event"] for e in events]
['session_created', 'window_started', 'pane_creating',
 'window_done', 'workspace_built']
>>> next(e for e in events if e["event"] == "session_created")["session_pane_total"]
1

Build events with before_script: before_script_started fires before the script runs; before_script_done fires in finally (success or failure).

>>> script_events: list[dict] = []
>>> script_event_cfg = {
...     "session_name": "script-events-demo",
...     "before_script": "echo hello",
...     "windows": [{"window_name": "main", "panes": [{"shell_command": []}]}],
... }
>>> builder = ClassicWorkspaceBuilder(
...     session_config=script_event_cfg,
...     server=server,
...     on_build_event=script_events.append,
... )
>>> builder.build()
>>> event_names = [e["event"] for e in script_events]
>>> "before_script_started" in event_names
True
>>> "before_script_done" in event_names
True
>>> bs_start = event_names.index("before_script_started")
>>> bs_done = event_names.index("before_script_done")
>>> win_start = event_names.index("window_started")
>>> bs_start < bs_done < win_start
True

Discussed in Python workspace builder behavior , Python workspace internal API

Members

server

server : Server attribute [source] ¶ attribute [source] ¶ server

session_name

session_name : str attribute [source] ¶ attribute [source] ¶ session_name

on_progress

on_progress : t.Callable[[str], None] | None attribute [source] ¶ attribute [source] ¶ on_progress

on_before_script

on_before_script : t.Callable[[], None] | None attribute [source] ¶ attribute [source] ¶ on_before_script

on_script_output

on_script_output : t.Callable[[str], None] | None attribute [source] ¶ attribute [source] ¶ on_script_output

on_build_event

on_build_event : t.Callable[[dict[str, t.Any]], None] | None attribute [source] ¶ attribute [source] ¶ on_build_event

__init__

__init__ ( self , session_config : dict[str, t.Any] , server : Server , plugins : list[t.Any] | None = None , on_progress : t.Callable[[str], None] | None = None , on_before_script : t.Callable[[], None] | None = None , on_script_output : t.Callable[[str], None] | None = None , on_build_event : t.Callable[[dict[str, t.Any]], None] | None = None ) → None method [source] ¶ method [source] ¶ __init__

Initialize workspace loading.

Parameters

session_config ( dict[str, t.Any] ) – session config, includes a list of windows.
server ( Server ) – tmux server to build session in
plugins ( list[t.Any] | None ) – plugins to be used for this session
on_progress ( t.Callable[[str], None] | None ) – callback for progress updates during building
on_before_script ( t.Callable[[], None] | None ) – called just before before_script runs; use to clear the terminal (e.g. stop a spinner) so script output is not interleaved
on_script_output ( t.Callable[[str], None] | None ) – called with each output line from before_script subprocess; when set, raw TTY tee is suppressed so the caller can route lines to a live panel instead
on_build_event ( t.Callable[[dict[str, t.Any]], None] | None ) – called with a dict event at each structural build milestone (session created, window started/done, pane creating, workspace built); used by the CLI to render a live session tree

session

session ( self ) → Session property [source] ¶ property [source] ¶ session

Return tmux session using in workspace builder session.

Discussed in Python workspace builder example , Python workspace internal API

session_exists

session_exists ( self , session_name : str ) → bool method [source] ¶ method [source] ¶ session_exists: Return true if tmux session already exists.

build

build ( self , session : Session | None = None , append : bool = False ) → None method [source] ¶ method [source] ¶ build

Build tmux workspace in session.

Optionally accepts session to build with only session object.

Without session, it will use libtmux.Server at self.server passed in on initialization to create a new Session object.

Parameters

session ( Session | None ) – session to build workspace in
append ( bool ) – append windows in current active session

In other ports Build a session from a workspace description

Ruby LibTmux::Workspace::Plan#apply
Lua No source-verified Lua equivalent is recorded for this operation.
TypeScript builder.applyWorkspace
Rust src.WorkspaceBuilder.build
Go workspace.Build
Java io.github.libtmux.workspace.WorkspaceBuilder.WorkspaceBuilder.build
.NET LibTmux.Workspace.WorkspaceBuilder.BuildAsync
C++ libtmux::workspace::build
Swift WorkspaceBuilder.build(_:on:)

iter_create_windows

iter_create_windows ( self , session : Session , append : bool = False ) → Iterator[t.Any] method [source] ¶ method [source] ¶ iter_create_windows

Return libtmux.Window iterating through session config dict.

Generator yielding libtmux.Window by iterating through session_config['windows'].

Applies window_options to window.

Parameters

session ( Session ) – session to create windows in
append ( bool ) – append windows in current active session

Returns

tuple of ( libtmux.Window , window_config) Newly created window, and the section from the tmuxp configuration that was used to create the window.

iter_create_panes

iter_create_panes ( self , window : Window , window_config : dict[str, t.Any] ) → Iterator[t.Any] method [source] ¶ method [source] ¶ iter_create_panes

Return libtmux.Pane iterating through window config dict.

Run shell_command with $ tmux send-keys.

Parameters

window ( Window ) – window to create panes for
window_config ( dict[str, t.Any] ) – config section for window

Returns

tuple of ( libtmux.Pane , pane_config) Newly created pane, and the section from the tmuxp configuration that was used to create the pane.

config_after_window

config_after_window ( self , window : Window , window_config : dict[str, t.Any] ) → None method [source] ¶ method [source] ¶ config_after_window

Actions to apply to window after window and pane finished.

When building a tmux session, sometimes its easier to postpone things like setting options until after things are already structurally prepared.

Parameters

window ( Window ) – window to create panes for
window_config ( dict[str, t.Any] ) – config section for window

find_current_attached_session

find_current_attached_session ( self ) → Session method [source] ¶ method [source] ¶ find_current_attached_session: Return current attached session.

first_window_pass

first_window_pass ( self , i : int , session : Session , append : bool ) → bool method [source] ¶ method [source] ¶ first_window_pass: Return True first window, used when iterating session windows.