Builder - tmuxp.workspace.builder

Create a tmux workspace from a workspace dict.

tmuxp.workspace.builder._wait_for_pane_ready(pane, timeout=2.0, interval=0.05)

Wait for pane shell to draw its prompt.

Polls the pane’s cursor position until it moves from origin (0, 0), indicating the shell has finished initializing and drawn its prompt.

Return type:

bool

Parameters:

• pane (libtmux.Pane) – pane to wait for

• timeout (float) – maximum seconds to wait before giving up

• interval (float) – seconds between polling attempts

Returns:

True if pane became ready, False on timeout or error

Return type:

bool

Examples

>>> pane = session.active_window.active_pane

Wait for the shell to be ready:

>>> _wait_for_pane_ready(pane, timeout=5.0)
True

tmuxp.workspace.builder.get_default_columns()

Return default session column size use when building new tmux sessions.

Return type:

int

tmuxp.workspace.builder.get_default_rows()

Return default session row size use when building new tmux sessions.

Return type:

int

class tmuxp.workspace.builder.WorkspaceBuilder(session_config, server, plugins=None, on_progress=None, on_before_script=None, on_script_output=None, on_build_event=None)

Bases: object

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 = WorkspaceBuilder(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 = WorkspaceBuilder(
...     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 = WorkspaceBuilder(
...     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 = WorkspaceBuilder(
...     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 = WorkspaceBuilder(
...     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 = WorkspaceBuilder(
...     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

The normal phase of loading is:

1. Load JSON / YAML file via pathlib.Path:

   from tmuxp._internal import config_reader
   session_config = config_reader.ConfigReader._load(raw_yaml)
   

   The reader automatically detects the file type from pathlib.suffix.

   We can also parse raw file:

   import pathlib
   from tmuxp._internal import config_reader
   
   session_config = config_reader.ConfigReader._from_file(
       pathlib.Path('path/to/config.yaml')
   )
   

2. config.expand() session_config inline shorthand:

   from tmuxp import config
   session_config = config.expand(session_config)
   

3. config.trickle() passes down default values from session -> window -> pane if applicable:

   session_config = config.trickle(session_config)
   

4. (You are here) We will create a libtmux.Session (a real tmux(1) session) and iterate through the list of windows, and their panes, returning full libtmux.Window and libtmux.Pane objects each step of the way:

   workspace = WorkspaceBuilder(session_config=session_config, server=server)
   

It handles the magic of cases where the user may want to start a session inside tmux (when $TMUX is in the env variables).

session_name: str

server: Server

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

_session: Session | None

property session: Session

Return tmux session using in workspace builder session.

session_exists(session_name)

Return true if tmux session already exists.

Return type:

bool

build(session=None, append=False)

Build tmux workspace in session.

Optionally accepts session to build with only session object.

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

Return type:

None

Parameters:

• session (libtmux.Session) – session to build workspace in

• append (bool) – append windows in current active session

iter_create_windows(session, append=False)

Return libtmux.Window iterating through session config dict.

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

Applies window_options to window.

Return type:

Iterator[t.Any]

Parameters:

• session (libtmux.Session) – session to create windows in

• append (bool) – append windows in current active session

Returns:

Newly created window, and the section from the tmuxp configuration that was used to create the window.

Return type:

tuple of (libtmux.Window, window_config)

iter_create_panes(window, window_config)

Return libtmux.Pane iterating through window config dict.

Run shell_command with $ tmux send-keys.

Return type:

Iterator[t.Any]

Parameters:

• window (libtmux.Window) – window to create panes for

• window_config (dict) – config section for window

Returns:

Newly created pane, and the section from the tmuxp configuration that was used to create the pane.

Return type:

tuple of (libtmux.Pane, pane_config)

config_after_window(window, window_config)

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.

Return type:

None

Parameters:

• window (libtmux.Window) – window to create panes for

• window_config (dict) – config section for window

find_current_attached_session()

Return current attached session.

Return type:

Session

first_window_pass(i, session, append)

Return True first window, used when iterating session windows.

Return type:

bool