Builder - tmuxp.workspace.builder

Create a tmux workspace from a workspace dict.

class tmuxp.workspace.builder.WorkspaceBuilder(session_config, server, plugins=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']

The normal phase of loading is:

1. Load JSON / YAML file via 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

_session: Optional[Session]

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[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[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