Builder - tmuxp.workspace.builder

Create a tmux workspace from a workspace dict.

tmuxp.workspace.builder.get_default_columns()[source]

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

Return type:

int

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

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

Return type:

int

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

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

Return true if tmux session already exists.

Return type:

bool

build(session=None, append=False)[source]

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

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

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

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

Return current attached session.

Return type:

Session

first_window_pass(i, session, append)[source]

Return True first window, used when iterating session windows.

Return type:

bool