API Reference#

Internals#

Warning

Be careful with these! Internal APIs are not covered by version policies. They can break or be removed between minor versions.

If you need an internal API stabilized please file an issue.

util.run_before_script(cwd=None)[source]#: Function to wrap try/except for subprocess.check_call().

util.oh_my_zsh_auto_title()[source]#

Give warning and offer to fix DISABLE_AUTO_TITLE.

see: https://github.com/robbyrussell/oh-my-zsh/pull/257

util.raise_if_tmux_not_running()[source]#: Raise exception if not running. More descriptive error if no server found.

util.get_current_pane()[source]#: Return Pane if one found in env

util.get_session(session_name=None, current_pane=None)[source]#

util.get_window(window_name=None, current_pane=None)[source]#

util.get_pane(current_pane=None)[source]#

CLI#

import_config.get_teamocil_dir()[source]#

Return teamocil configuration directory.

Returns:: absolute path to teamocil config directory
Return type:: str

Workspace files#

Finding#

finders.is_workspace_file(extensions=['.yml', '.yaml', '.json'])[source]#

Return True if file has a valid workspace file type.

Parameters:

filename (str) – filename to check (e.g. mysession.json).
extensions (str or list) – filetypes to check (e.g. ['.yaml', '.json']).

Return type:

bool

finders.in_dir(extensions=['.yml', '.yaml', '.json'])[source]#

Return a list of workspace_files in workspace_dir.

Parameters:

workspace_dir (str) – directory to search
extensions (list) – filetypes to check (e.g. ['.yaml', '.json']).

Return type:

list

finders.in_cwd()[source]#

Return list of workspace_files in current working directory.

If filename is .tmuxp.py, .tmuxp.json, .tmuxp.yaml.

Returns:: workspace_files in current working directory
Return type:: list

Examples

>>> sorted(in_cwd())
['.tmuxp.json', '.tmuxp.yaml']

finders.get_workspace_dir()[source]#

Return tmuxp workspace directory.

TMUXP_CONFIGDIR environmental variable has precedence if set. We also evaluate XDG default directory from XDG_CONFIG_HOME environmental variable if set or its default. Then the old default ~/.tmuxp is returned for compatibility.

Returns:: absolute path to tmuxp config directory
Return type:: str
Return type:: str

Validation#

tmuxp.workspace.validation.validate_schema(workspace_dict)[source]#

Return True if workspace schema is correct.

Parameters:: workspace_dict (dict) – tmuxp workspace data
Return type:: bool

Processing#

loader.expandshell()[source]#

Return expanded path based on user’s $HOME and env.

os.path.expanduser() and os.path.expandvars().

Parameters:: path (str) – path to expand
Returns:: path with shell variables expanded
Return type:: str

loader.expand(cwd=None, parent=None)[source]#

Return workspace with shorthand and inline properties expanded.

This is necessary to keep the code in the WorkspaceBuilder clean and also allow for neat, short-hand “sugarified” syntax.

As a simple example, internally, tmuxp expects that workspace options like shell_command are a list (array):

'shell_command': ['htop']

tmuxp workspace allow for it to be simply a string:

'shell_command': 'htop'

ConfigReader will load JSON/YAML files into python dicts for you.

Parameters:

workspace_dict (dict) – the tmuxp workspace for the session
cwd (str) – directory to expand relative paths against. should be the dir of the workspace directory.
parent (str) – (used on recursive entries) start_directory of parent window or session object.

Return type:

dict

loader.trickle()[source]#

Return a dict with “trickled down” / inherited workspace values.

This will only work if workspace has been expanded to full form with loader.expand().

tmuxp allows certain commands to be default at the session, window level. shell_command_before trickles down and prepends the shell_command for the pane.

Parameters:: workspace_dict (dict) – the tmuxp workspace.
Return type:: dict

Workspace importers#

importers.import_teamocil()[source]#

Return tmuxp workspace from a `teamocil`_ yaml workspace.

Parameters:: workspace_dict (dict) – python dict for tmuxp workspace

Notes

Todos:

change ‘root’ to a cd or start_directory
width in pane -> main-pain-width
with_env_var
clear
cmd_separator

importers.import_tmuxinator()[source]#

Return tmuxp workspace from a `tmuxinator`_ yaml workspace.

Parameters:: workspace_dict (dict) – python dict for tmuxp workspace.
Return type:: dict

Configuration reader#

class tmuxp.config_reader.ConfigReader(content)[source]#

Bases: object

Parse string data (YAML and JSON) into a dictionary.

>>> cfg = ConfigReader({ "session_name": "my session" })
>>> cfg.dump("yaml")
'session_name: my session\n'
>>> cfg.dump("json")
'{\n  "session_name": "my session"\n}'

static _load(format, content)[source]#

Load raw config data and directly return it.

>>> ConfigReader._load("json", '{ "session_name": "my session" }')
{'session_name': 'my session'}

>>> ConfigReader._load("yaml", 'session_name: my session')
{'session_name': 'my session'}

classmethod load(format, content)[source]#

Load raw config data into a ConfigReader instance (to dump later).

>>> cfg = ConfigReader.load("json", '{ "session_name": "my session" }')
>>> cfg
<tmuxp.config_reader.ConfigReader object at ...>
>>> cfg.content
{'session_name': 'my session'}

>>> cfg = ConfigReader.load("yaml", 'session_name: my session')
>>> cfg
<tmuxp.config_reader.ConfigReader object at ...>
>>> cfg.content
{'session_name': 'my session'}

classmethod _from_file(path)[source]#

Load data from file path directly to dictionary.

YAML file

For demonstration only, create a YAML file:

>>> yaml_file = tmp_path / 'my_config.yaml'
>>> yaml_file.write_text('session_name: my session', encoding='utf-8')
24

Read YAML file:

>>> ConfigReader._from_file(yaml_file)
{'session_name': 'my session'}

JSON file

For demonstration only, create a JSON file:

>>> json_file = tmp_path / 'my_config.json'
>>> json_file.write_text('{"session_name": "my session"}', encoding='utf-8')
30

Read JSON file:

>>> ConfigReader._from_file(json_file)
{'session_name': 'my session'}

classmethod from_file(path)[source]#

Load data from file path

YAML file

For demonstration only, create a YAML file:

>>> yaml_file = tmp_path / 'my_config.yaml'
>>> yaml_file.write_text('session_name: my session', encoding='utf-8')
24

Read YAML file:

>>> cfg = ConfigReader.from_file(yaml_file)
>>> cfg
<tmuxp.config_reader.ConfigReader object at ...>

>>> cfg.content
{'session_name': 'my session'}

JSON file

For demonstration only, create a JSON file:

>>> json_file = tmp_path / 'my_config.json'
>>> json_file.write_text('{"session_name": "my session"}', encoding='utf-8')
30

Read JSON file:

>>> cfg = ConfigReader.from_file(json_file)
>>> cfg
<tmuxp.config_reader.ConfigReader object at ...>

>>> cfg.content
{'session_name': 'my session'}

static _dump(format, content, indent=2, **kwargs)[source]#

Dump directly.

>>> ConfigReader._dump("yaml", { "session_name": "my session" })
'session_name: my session\n'

>>> ConfigReader._dump("json", { "session_name": "my session" })
'{\n  "session_name": "my session"\n}'

Return type:: str

dump(format, indent=2, **kwargs)[source]#

Dump via ConfigReader instance.

>>> cfg = ConfigReader({ "session_name": "my session" })
>>> cfg.dump("yaml")
'session_name: my session\n'
>>> cfg.dump("json")
'{\n  "session_name": "my session"\n}'

Return type:: str

Workspace Builder#

class tmuxp.workspace.builder.WorkspaceBuilder(sconf, plugins=[], server=None)[source]#

Bases: object

Load workspace from session dict.

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(sconf=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:

Load JSON / YAML file via via pathlib.Path:

from tmuxp import config_reader
sconf = 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 import config_reader

sconf = config_reader.ConfigReader._from_file(
    pathlib.Path('path/to/config.yaml')
)

config.expand() sconf inline shorthand:

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

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

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_exists(session_name=None)[source]#

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.

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 sconf['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, wconf)

iter_create_panes(w, wconf)[source]#

Return libtmux.Pane iterating through window config dict.

Run shell_command with $ tmux send-keys.

Parameters:

w (libtmux.Window) – window to create panes for
wconf (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, pconf)

config_after_window(w, wconf)[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.

Parameters:

w (libtmux.Window) – window to create panes for
wconf (dict) – config section for window

find_current_attached_session()[source]#

first_window_pass(i, session, append)[source]#

Workspace Freezer#

freezer.freeze()[source]#

Freeze live tmux session into a tmuxp workspacee.

Parameters:: session (libtmux.Session) – session object
Returns:: tmuxp compatible workspace
Return type:: dict

freezer.inline()[source]#

Return workspace with inlined shorthands. Opposite of loader.expand().

Parameters:: workspace_dict (dict) –
Returns:: workspace with shorthands inlined.
Return type:: dict

Exceptions#

exception tmuxp.exc.EmptyWorkspaceException[source]#

Bases: WorkspaceError

Workspace file is empty.

exception tmuxp.exc.WorkspaceError[source]#

Bases: TmuxpException

Error parsing tmuxp workspace data.

exception tmuxp.exc.BeforeLoadScriptError(returncode, cmd, output=None)[source]#

Bases: Exception

Exception replacing subprocess.CalledProcessError for tmuxp.util.run_before_script().

exception tmuxp.exc.BeforeLoadScriptNotExists(*args, **kwargs)[source]#: Bases: OSError