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

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

Configuration

Finding

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

Return True if file has a valid config file type.

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

bool

config.in_dir(config_dir=u'/home/docs/.tmuxp', extensions=[u'.yml', u'.yaml', u'.json'])

Return a list of configs in config_dir.

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

list

config.in_cwd()

Return list of configs in current working directory.

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

Return type:list

Import and export

config.validate_schema(sconf)

Return True if config schema is correct.

Parameters:sconf (dict) – session configuration
Return type:bool
config.expandshell(_path)

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

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

Parameters:_path (string) – path to expand
Returns:expanded path
Return type:string
config.expand(sconf, cwd=None, parent=None)

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 (string) – 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.
Return type:

dict

config.inline(sconf)

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

Parameters:sconf (dict) – unexpanded config file
Return type:dict
config.trickle(sconf)

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
Return type:dict
config.import_teamocil(sconf)

Return tmuxp config from a teamocil yaml config.

Todo:change ‘root’ to a cd or start_directory
Todo:width in pane -> main-pain-width
Todo:with_env_var
Todo:clear
Todo:cmd_separator
Parameters:sconf (dict) – python dict for session configuration
config.import_tmuxinator(sconf)

Return tmuxp config from a tmuxinator yaml config.

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

Workspace Builder

class tmuxp.WorkspaceBuilder(sconf, server=None)

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 Session (a real tmux(1) session) and iterate through the list of windows, and their panes, returning full Window and 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)

Build tmux workspace in session.

Optionally accepts session to build with only session object.

Without session, it will use Server at self.server passed in on initialization to create a new Session object.

Parameters:session (Session) –
  • session to build workspace in
iter_create_panes(w, wconf)

Return Pane iterating through window config dict.

Run shell_command with $ tmux send-keys.

Parameters:
  • w (Window) – window to create panes for
  • wconf (dict) – config section for window
Return type:

tuple(Pane, pconf)

iter_create_windows(s)

Return Window iterating through session config dict.

Generator yielding Window by iterating through sconf['windows'].

Applies window_options to window.

Parameters:sessionSession from the config
Return type:tuple(Window, wconf)

Exceptions

exception tmuxp.exc.EmptyConfigException

Configuration is empty.

exception tmuxp.exc.ConfigError

Error parsing tmuxp configuration dict.

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

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

exception tmuxp.exc.BeforeLoadScriptNotExists(*args, **kwargs)