`tmuxp.workspace.builder.ClassicWorkspaceBuilder`

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

Load workspace from workspace dict object.

Description#

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 attribute [source] ¶

session_name : str attribute [source] ¶

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

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

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

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

__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] ¶

Initialize workspace loading.

Description#

Notes

TODO: Initialize libtmux.Session from here, in self.session.

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 (self) → Session property [source] ¶

Return tmux session using in workspace builder session.

Discussed in Python workspace builder example , Python workspace internal API

session_exists (self, session_name: str) → bool method [source] ¶

Return true if tmux session already exists.

Parameters

session_name (str) #

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

Build tmux workspace in session.

Description#

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

PowerShell
LibTmux.Workspace\Invoke-TmuxWorkspace
Applies the exact reviewed -Plan after PowerShell confirmation. -WhatIf previews without applying it; application is detached.
Julia
LibTmuxWorkspace.apply
Applies a prepared WorkspacePlan on an explicit Server , detached and under one deadline. Existing session names fail unless reuse is explicit.
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.build
C#
LibTmux.Workspace.WorkspaceBuilder.BuildAsync
C++
libtmux::workspace::build
Swift
WorkspaceBuilder.build(_:on:)
Kotlin
No source-verified Kotlin equivalent is recorded for this operation.
Scala
No source-verified Scala equivalent is recorded for this operation.
F#
No source-verified F# equivalent is recorded for this operation.

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

Return libtmux.Window iterating through session config dict.

Description#

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 ( self, window: Window, window_config: dict[str, t.Any] ) → Iterator[t.Any] method [source] ¶

Return libtmux.Pane iterating through window config dict.

Description#

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 ( self, window: Window, window_config: dict[str, t.Any] ) → None method [source] ¶

Actions to apply to window after window and pane finished.

Description#

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 (self) → Session method [source] ¶: Return current attached session.

first_window_pass ( self, i: int, session: Session, append: bool ) → bool method [source] ¶

Return True first window, used when iterating session windows.

Parameters

i (int) #
session (Session) #
append (bool) #

Scripting & web

Compiled & native

JVM

.NET

tmux

`tmuxp.workspace.builder.ClassicWorkspaceBuilder`

Description#

Examples#

Members

Description#

Description#

Description#

Description#

Description#