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

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.

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() ¶ function[source]

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

Return type:: int

tmuxp.workspace.builder.get_default_rows() ¶ function[source]

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

Return type:: int

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

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:

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')
)

config.expand() session_config inline shorthand:

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

config.trickle() passes down default values from session -> window -> pane if applicable:
```
session_config = config.trickle(session_config)
```
(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).

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

Initialize workspace loading.

Parameters:

session_config (dict) – session config, includes a list of windows.
plugins (list) – plugins to be used for this session
server (libtmux.Server) – tmux server to build session in
on_progress (callable, optional) – callback for progress updates during building
on_before_script (callable, optional) – 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 (callable, optional) – 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 (callable, optional) – 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

Return type:

None

Notes

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

iter_create_windows(session, append=False) ¶ method[source]

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 (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)

Builder - tmuxp.workspace.builder¶

Builder - `tmuxp.workspace.builder`¶