API Reference¶
See also
See libtmux’s API and Quickstart to see how you can control tmux via python API calls.
Internals¶
CLI¶
-
cli.
_reattach
()[source]¶ Reattach session (depending on env being inside tmux already or not)
Parameters: builder ( workspacebuilder.WorkspaceBuilder
) –Notes
If
TMUX
environmental variable exists in the environment this script is running, that means we’re in a tmux client. Sotmux 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
-
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
-
cli.
load_workspace
(socket_name=None, socket_path=None, tmux_config_file=None, new_session_name=None, colors=None, detached=False, answer_yes=False, append=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 to attach in new session. Default False.
- append (bool) – Assume current when given prompt to append windows in same session. Default False.
Notes
tmuxp will check and load a configuration file. The file will use kaptan to load a JSON/YAML into a
dict
. Thenconfig.expand()
andconfig.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
orswitch-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: Returns: Return type:
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
andenv
.os.path.expanduser()
andos.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: Returns: Return type:
-
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, plugins=[], 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:
kaptan imports json/yaml/ini.
.get()
returns pythondict
: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.
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 realtmux(1)
session) and iterate through the list of windows, and their panes, returning fulllibtmux.Window
andlibtmux.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, append=False)[source]¶ Build tmux workspace in session.
Optionally accepts
session
to build with only session object.Without
session
, it will uselibmtux.Server
atself.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
- session (
-
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
- w (
-
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
)- w (
-
iter_create_windows
(session, append=False)[source]¶ Return
libtmux.Window
iterating through session config dict.Generator yielding
libtmux.Window
by iterating throughsconf['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
)- session (
-
workspacebuilder.
freeze
()[source]¶ Freeze live tmux session and Return session config
dict
.Parameters: session ( libtmux.Session
) – session objectReturns: tmuxp compatible workspace config Return type: dict
Exceptions¶
-
exception
tmuxp.exc.
BeforeLoadScriptError
(returncode, cmd, output=None)[source]¶ Exception replacing
subprocess.CalledProcessError
fortmuxp.util.run_before_script()
.