API Reference

See also

See libtmux’s API and Quickstart to see how you can control tmux via python API calls.

Internals

util.run_before_script(cwd=None)[source]

Function to wrap try/except for subprocess.check_call().

CLI

cli._reattach()[source]

Reattach session (depending on env being inside tmux already or not)

Parameters:session (libtmux.Session) –

Notes

If TMUX environmental variable exists in the environment this script is running, that means we’re in a tmux client. So tmux switch-client will load the session.

If not, tmux attach-session loads the client to the target session.

cli.get_config_dir()[source]

Return tmuxp configuration 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
cli.get_teamocil_dir()[source]

Return teamocil configuration directory.

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

See also

tmuxp.config.import_teamocil()

cli.get_tmuxinator_dir()[source]

Return tmuxinator configuration directory.

Checks for TMUXINATOR_CONFIG environmental variable.

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

See also

tmuxp.config.import_tmuxinator()

cli.load_workspace(socket_name=None, socket_path=None, new_session_name=None, colors=None, detached=False, answer_yes=False)[source]

Load a tmux “workspace” session via tmuxp file.

Parameters:
  • config_file (str) – absolute path to config file
  • socket_name (str, optional) – tmux -L <socket-name>
  • socket_path (str, optional) – tmux -S <socket-path>
  • new_session_name (str, options) – tmux new -s <new_session_name>
  • colors (str, optional) –
    ‘-2’
    Force tmux to support 256 colors
  • detached (bool) – Force detached state. default False.
  • answer_yes (bool) – Assume yes when given prompt. default False.

Notes

tmuxp will check and load a configuration file. The file will use kaptan to load a JSON/YAML into a dict. Then config.expand() and config.trickle() will be used to expand any shorthands, template variables, or file paths relative to where the config/script is executed from.

config.expand() accepts the directory of the config file, so the user’s configuration can resolve absolute paths relative to where the config file is. In otherwords, if a config file at /var/moo/hi.yaml has ./ in its configs, we want to be sure any file path with ./ is relative to /var/moo, not the user’s PWD.

A libtmux.Server object is created. No tmux server is started yet, just the object.

The prepared configuration and the server object is passed into an instance of WorkspaceBuilder.

A sanity check against libtmux.common.which() is ran. It will raise an exception if tmux isn’t found.

If a tmux session under the same name as session_name in the tmuxp configuration exists, tmuxp offers to attach the session. Currently, tmuxp does not allow appending a workspace / incremental building on top of a current session (pull requests are welcome!).

build() will build the session in the background via using tmux’s detached state (-d).

After the session (workspace) is built, unless the user decided to load the session in the background via tmuxp -d (which is in the spirit of tmux’s -d), we need to prompt the user to attach the session.

If the user is already inside a tmux client, which we detect via the TMUX environment variable bring present, we will prompt the user to switch their current client to it.

If they’re outside of tmux client - in a plain-old PTY - we will automatically attach.

If an exception is raised during the building of the workspace, tmuxp will prompt to cleanup ($ tmux kill-session) the session on the user’s behalf. An exception raised during this process means it’s not easy to predict how broken the session is.

Changed in version tmux: 2.6+

In tmux 2.6, the way layout and proportion’s work when interfacing with tmux in a detached state (outside of a client) changed. Since tmuxp builds workspaces in a detached state, the WorkspaceBuilder isn’t able to rely on functionality requiring awarness of session geometry, e.g. set-layout.

Thankfully, tmux is able to defer commands to run after the user performs certain actions, such as loading a client via attach-session or switch-client.

Upon client switch, client-session-changed is triggered [1].

References

[1]cmd-switch-client.c hook. GitHub repo for tmux. https://github.com/tmux/tmux/blob/2.6/cmd-switch-client.c#L132. Accessed April 8th, 2018.
cli._validate_choices()[source]

Callback wrapper for validating click.prompt input.

Parameters:options (list) – List of allowed choices
Returns:callback function for value_proc in click.prompt().
Return type:callable()
Raises:click.BadParameter –

Configuration

Finding

config.is_config_file(extensions=['.yml', '.yaml', '.json'])[source]

Return True if file has a valid config file type.

Parameters:
  • filename (str) – filename to check (e.g. mysession.json).
  • extensions (str or list) – filetypes to check (e.g. ['.yaml', '.json']).
Returns:
Return type:

bool
config.in_dir(extensions=['.yml', '.yaml', '.json'])[source]

Return a list of configs in config_dir.

Parameters:
  • config_dir (str) – directory to search
  • extensions (list) – filetypes to check (e.g. ['.yaml', '.json']).
Returns:
Return type:

list
config.in_cwd()[source]

Return list of configs in current working directory.

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

Returns:configs in current working directory
Return type:list

Import and export

config.validate_schema()[source]

Return True if config schema is correct.

Parameters:sconf (dict) – session configuration
Returns:
Return type:bool
config.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
config.expand(cwd=None, parent=None)[source]

Return config with shorthand and inline properties expanded.

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

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

'shell_command': ['htop']

tmuxp configs allow for it to be simply a string:

'shell_command': 'htop'

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

Parameters:
  • sconf (dict) – the configuration for the session
  • cwd (str) – directory to expand relative paths against. should be the dir of the config directory.
  • parent (str) – (used on recursive entries) start_directory of parent window or session object.
Returns:
Return type:

dict
config.inline()[source]

Return config in inline form, opposite of config.expand().

Parameters:sconf (dict) –
Returns:configuration with optional inlined configs.
Return type:dict
config.trickle()[source]

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

This will only work if config has been expanded to full form with config.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:sconf (dict) – the session configuration.
Returns:
Return type:dict
config.import_teamocil()[source]

Return tmuxp config from a teamocil yaml config.

Parameters:sconf (dict) – python dict for session configuration

Notes

Todos:

  • change ‘root’ to a cd or start_directory
  • width in pane -> main-pain-width
  • with_env_var
  • clear
  • cmd_separator
config.import_tmuxinator()[source]

Return tmuxp config from a tmuxinator yaml config.

Parameters:sconf (dict) – python dict for session configuration.
Returns:
Return type:dict

Workspace Builder

class tmuxp.workspacebuilder.WorkspaceBuilder(sconf, server=None)[source]

Load workspace from session dict.

Build tmux workspace from a configuration. Creates and names windows, sets options, splits windows into panes.

The normal phase of loading is:

  1. kaptan imports json/yaml/ini. .get() returns python dict:

    import kaptan
sconf = kaptan.Kaptan(handler='yaml')
sconf = sconfig.import_config(self.yaml_config).get()

    or from config file with extension:

    import kaptan
sconf = kaptan.Kaptan()
sconf = sconfig.import_config('path/to/config.yaml').get()

    kaptan automatically detects the handler from filenames.

  2. config.expand() sconf inline shorthand:

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

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

    sconf = config.trickle(sconf)

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

build(session=None)[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
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
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)
iter_create_windows(s)[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
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)
workspacebuilder.freeze()[source]

Freeze live tmux session and Return session config dict.

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

Exceptions

exception tmuxp.exc.EmptyConfigException[source]

Configuration is empty.

exception tmuxp.exc.ConfigError[source]

Error parsing tmuxp configuration dict.

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

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

exception tmuxp.exc.BeforeLoadScriptNotExists(*args, **kwargs)[source]