注解
tmuxp is usable but still needs your help reporting errors, bugs and usability feedback. If you encounter an error, please post on the Issue tracker.
API Reference¶
Server Object¶
- class tmuxp.Server(socket_name=None, socket_path=None, config_file=None, colors=None, **kwargs)¶
基类:tmuxp.util.TmuxRelationalObject
The tmux(1) server.
- Server._sessions [Session, ...]
- Session._windows [Window, ...]
- Window._panes [Pane, ...]
- Session._windows [Window, ...]
When instantiated, provides the t global. stores information on live, running tmux server.
- childIdAttribute = 'session_id'¶
unique child ID key
- socket_name = None¶
[-L socket-name]
- socket_path = None¶
[-S socket-path]
- config_file = None¶
[-f file]
- colors = None¶
-2 or -8
- _list_sessions()¶
Return list of sessions in dict form.
Retrieved from $ tmux(1) list-sessions stdout.
The list is derived from stdout in util.tmux which wraps Subprocess.Popen().
返回类型: list of dict
- _sessions¶
Property / alias to return _list_sessions().
- sessions¶
Property / alias to return list_sessions().
- _list_windows()¶
Return list of windows in dict form.
Retrieved from $ tmux(1) list-windows stdout.
The list is derived from stdout in util.tmux which wraps Subprocess.Popen().
返回类型: list
- _list_panes()¶
Return list of panes in dict form.
Retrieved from $ tmux(1) list-panes stdout.
The list is derived from stdout in util.tmux which wraps Subprocess.Popen().
返回类型: list
- attached_sessions()¶
Return active Session object.
This will not work where multiple tmux sessions are attached.
返回类型: Server
- has_session(target_session)¶
Return True if session exists. $ tmux has-session.
Param: target_session: str of session name. 返回类型: bool
- kill_server()¶
$ tmux kill-server.
- findWhere(attrs)¶
Return object on first match.
Based on .findWhere() from underscore.js.
- getById(id)¶
Return object based on .get() from backbone.js.
参数: id (string) – 返回类型: object
- kill_session(target_session=None)¶
Kill the tmux session with $ tmux kill-session, return self.
Param: target_session: str. note this accepts fnmatch(3). ‘asdf’ will kill ‘asdfasd’. 返回类型: Server
- where(attrs, first=False)¶
Return objects matching child objects properties.
Based on .where() from underscore.js.
参数: attrs (dict) – tmux properties to match 返回类型: list
- switch_client(target_session)¶
$ tmux switch-client.
Param: target_session: str. name of the session. fnmatch(3) works.
- attach_session(target_session=None)¶
$ tmux attach-session aka alias: $ tmux attach.
Param: target_session: str. name of the session. fnmatch(3) works.
- new_session(session_name=None, kill_session=False, attach=False, *args, **kwargs)¶
Return Session from $ tmux new-session.
Uses -P flag to print session info, -F for return formatting returns new Session object.
$ tmux new-session -d will create the session in the background $ tmux new-session -Ad will move to the session name if it already exists. todo: make an option to handle this.
参数: - session_name (string) –
session name:
$ tmux new-session -s <session_name>
- detach (bool) –
create session background:
$ tmux new-session -d
- attach_if_exists (bool) – if the session_name exists, attach it. if False, this method will raise a tmuxp.exc.TmuxSessionExists exception
- kill_session (bool) – Kill current session if $ tmux has-session Useful for testing workspaces.
返回类型: - session_name (string) –
- Server._sessions [Session, ...]
Session Object¶
- class tmuxp.Session(server=None, **kwargs)¶
基类:tmuxp.util.TmuxMappingObject, tmuxp.util.TmuxRelationalObject
tmux(1) session.
Holds Window objects.
- tmux(*args, **kwargs)¶
Return Server.tmux().
返回类型: Server.tmux
- attach_session(target_session=None)¶
Return $ tmux attach-session aka alias: $ tmux attach.
Param: target_session: str. name of the session. fnmatch(3) works.
- kill_session()¶
$ tmux kill-session.
- switch_client(target_session=None)¶
$ tmux kill-session.
Param: target_session: str. note this accepts fnmatch(3). ‘asdf’ will kill asdfasd
- rename_session(new_name)¶
Rename session and return new Session object.
参数: rename_session (string) – new session name 返回类型: Session
- new_window(window_name=None, start_directory=None, attach=True)¶
Return Window from $ tmux new-window.
注解
By default, this will make the window active. For the new window to be created and not set to current, pass in attach=False.
参数: window_name – window name. $ tmux new-window -n <window_name> -c <start_directory>
参数: - start_directory (string) – specifies the working directory in which the new created.
- attach – make new window the current window after creating it, default True.
- type – bool
返回类型:
- kill_window(target_window=None)¶
$ tmux kill-window.
Kill the current window or the window at target-window. removing it from any sessions to which it is linked.
参数: target_window (string) – the target window.
- _windows¶
Property / alias to return _list_windows().
- windows¶
Property / alias to return list_windows().
- select_window(target_window)¶
Return Window selected via $ tmux select-window.
Param: window: target_window also ‘last-window’ (-l), ‘next-window’ (-n), or ‘previous-window’ (-p) 返回类型: Window Todo: assure -l, -n, -p work.
- set_option(option, value)¶
Set option $ tmux set-option <option> <value>.
todo: needs tests
参数: - option (string) – the window option. such as ‘default-shell’.
- value (string or bool) – window value. True/False will turn in ‘on’ and ‘off’.
- show_options(option=None)¶
Return a dict of options for the window.
For familiarity with tmux, the option option param forwards to pick a single option, forwarding to Session.show_option().
参数: option (string) – optional. show a single option. 返回类型: dict
- show_option(option)¶
Return a list of options for the window.
Todo: test and return True/False for on/off string 参数: option (string) – option to return. 返回类型: string, int or bool
- findWhere(attrs)¶
Return object on first match.
Based on .findWhere() from underscore.js.
- getById(id)¶
Return object based on .get() from backbone.js.
参数: id (string) – 返回类型: object
- where(attrs, first=False)¶
Return objects matching child objects properties.
Based on .where() from underscore.js.
参数: attrs (dict) – tmux properties to match 返回类型: list
Window Object¶
- class tmuxp.Window(session=None, **kwargs)¶
基类:tmuxp.util.TmuxMappingObject, tmuxp.util.TmuxRelationalObject
tmux(1) window.
- tmux(cmd, *args, **kwargs)¶
Return Server.tmux() defaulting target_window as target.
Send command to tmux with window_id as target-window.
Specifying ('-t', 'custom-target') or ('-tcustom_target') in args will override using the object’s window_id as target.
返回类型: Server.tmux
- select_layout(layout=None)¶
Wrapper for $ tmux select-layout <layout>.
even-horizontal: Panes are spread out evenly from left to right across the window.
even-vertical: Panes are spread evenly from top to bottom.
main-horizontal: A large (main) pane is shown at the top of the window and the remaining panes are spread from left to right in the leftover space at the bottom.
main-vertical: Similar to main-horizontal but the large pane is placed on the left and the others spread from top to bottom along the right.
tiled: Panes are spread out as evenly as possible over the window in both rows and columns.
custom: custom dimensions (see tmux(1) manpages).
参数: layout (string) – string of the layout, ‘even-horizontal’, ‘tiled’, etc.
- set_window_option(option, value)¶
Wrapper for $ tmux set-window-option <option> <value>.
参数: value (string or bool) – window value. True/False will turn in ‘on’ and ‘off’.
- show_window_options(option=None)¶
Return a dict of options for the window.
For familiarity with tmux, the option option param forwards to pick a single option, forwarding to Window.show_window_option().
参数: option (string) – optional. show a single option. 返回类型: dict
- show_window_option(option)¶
Return a list of options for the window.
todo: test and return True/False for on/off string
参数: option (string) – option to return. 返回类型: string, int
- rename_window(new_name)¶
Return Window object $ tmux rename-window <new_name>.
参数: new_name (string) – name of the window
- move_window(destination)¶
Move the current Window object $ tmux move-window.
参数: destination – the target window or index to move the window to.
- select_pane(target_pane)¶
Return selected Pane through $ tmux select-pane.
参数: target_pane (string) – target_pane, or -U,``-D``, -L, -R or -l. 返回类型: Pane
- split_window(attach=True)¶
Split window and return the created Pane.
注解
tmux(1) will move window to the new pane if the split-window target is off screen. tmux handles the -d the same way as new-window and attach in Session.new_window.
By default, this will make the window the pane is created in active. To remain on the same window and split the pane in another target window, pass in attach=False.
Used for splitting window and holding in a python object.
参数: - attach – make new window the current window after creating it, default True.
- type – bool
返回类型:
- _panes¶
Property / alias to return _list_panes().
- panes¶
Property / alias to return list_panes().
- findWhere(attrs)¶
Return object on first match.
Based on .findWhere() from underscore.js.
- getById(id)¶
Return object based on .get() from backbone.js.
参数: id (string) – 返回类型: object
- where(attrs, first=False)¶
Return objects matching child objects properties.
Based on .where() from underscore.js.
参数: attrs (dict) – tmux properties to match 返回类型: list
Pane Object¶
- class tmuxp.Pane(window=None, **kwargs)¶
基类:tmuxp.util.TmuxMappingObject, tmuxp.util.TmuxRelationalObject
参数: window – Window - tmux(cmd, *args, **kwargs)¶
Return Server.tmux() defaulting to target_pane as target.
Send command to tmux with pane_id as target-pane.
Specifying ('-t', 'custom-target') or ('-tcustom_target') in args will override using the object’s pane_id as target.
返回类型: Server.tmux
- send_keys(cmd, enter=True)¶
$ tmux send-keys to the pane.
参数:
- clear()¶
Clear pane.
- reset()¶
Reset and clear pane history.
- resize_pane(*args, **kwargs)¶
$ tmux resize-pane of pane and return self.
参数: target_pane (string) – target_pane, or -U,``-D``, -L, -R. 返回类型: Pane
- enter()¶
Send carriage return to pane.
$ tmux send-keys send Enter to the pane.
- findWhere(attrs)¶
Return object on first match.
Based on .findWhere() from underscore.js.
- getById(id)¶
Return object based on .get() from backbone.js.
参数: id (string) – 返回类型: object
- where(attrs, first=False)¶
Return objects matching child objects properties.
Based on .where() from underscore.js.
参数: attrs (dict) – tmux properties to match 返回类型: list
Internals¶
- class tmuxp.util.TmuxRelationalObject¶
Base Class for managing tmux object child entities.
Manages collection of child objects (a Server has a collection of Session objects, a Session has collection of Window)
Children of TmuxRelationalObject are going to have a self.children, self.childIdAttribute and self.list_children.
Object .children .childIdAttribute method Server self._sessions ‘session_id’ Server.list_sessions() Session self._windows ‘window_id’ Session.list_windows() Window self._panes ‘pane_id’ Window.list_panes() Pane - findWhere(attrs)¶
Return object on first match.
Based on .findWhere() from underscore.js.
- getById(id)¶
Return object based on .get() from backbone.js.
参数: id (string) – 返回类型: object
- where(attrs, first=False)¶
Return objects matching child objects properties.
Based on .where() from underscore.js.
参数: attrs (dict) – tmux properties to match 返回类型: list
- class tmuxp.util.TmuxMappingObject¶
Base: collections.MutableMapping.
Convenience container. Base class for Pane, Window, Session and Server.
Instance attributes for useful information tmux(1) uses for Session, Window, Pane, stored self._TMUX. For example, a Window will have a window_id and window_name.
- class tmuxp.util.tmux(*args, **kwargs)¶
subprocess for tmux(1).
Usage:
proc = tmux('new-session', '-s%' % 'my session') if proc.stderr: raise exc.TmuxpException('Command: %s returned error: %s' % (proc.cmd, proc.stderr)) print('tmux command returned %s' % proc.stdout)
Equivalent to:
$ tmux new-session -s my session
- static util.has_required_tmux_version()¶
Return if tmux meets version requirement. Version >1.8 or above.
- static util.oh_my_zsh_auto_title()¶
Give warning and offer to fix DISABLE_AUTO_TITLE.
- static util.which(exe=None)¶
Return path of bin. Python clone of /usr/bin/which.
from salt.util - https://www.github.com/saltstack/salt - license apache
参数: exe (string) – Application to search PATHs for. 返回类型: string
Command Line¶
- static cli.prompt(name, default=None)¶
Return user input from command line.
prompt(), prompt_bool() and prompt_choices() are from flask-script. See the flask-script license.
参数: - name – prompt text
- default – default value if no input provided.
返回类型: string
- static cli.prompt_bool(name, default=False, yes_choices=None, no_choices=None)¶
Return user input from command line and converts to boolean value.
参数: - name – prompt text
- default – default value if no input provided.
- yes_choices – default ‘y’, ‘yes’, ‘1’, ‘on’, ‘true’, ‘t’
- no_choices – default ‘n’, ‘no’, ‘0’, ‘off’, ‘false’, ‘f’
返回类型: bool
- static cli.prompt_choices(name, choices, default=None, resolve=<function lower at 0x7f93e99c9398>, no_choice=('none', ))¶
Return user input from command line from set of provided choices.
参数: - name – prompt text
- choices – list or tuple of available choices. Choices may be single strings or (key, value) tuples.
- default – default value if no input provided.
- no_choice – acceptable list of strings for “null choice”
返回类型: str
- static cli.setup_logger(logger=None, level='INFO')¶
Setup logging for CLI use.
参数: logger (Logger) – instance of logger
- static cli.get_parser()¶
Return argparse.ArgumentParser instance for CLI.
- static cli.load_workspace(config_file, args)¶
Build config workspace.
参数: - config_file – full path to config file
- type – string
Configuration¶
Finding¶
- static config.is_config_file(filename, extensions=['.yml', '.yaml', '.json', '.ini'])¶
Return True if file has a valid config file type.
参数: - filename (string) – filename to check (e.g. mysession.json).
- extensions (list or string) – filetypes to check (e.g. ['.yaml', '.json']).
返回类型: bool
- static config.in_dir(config_dir='/home/docs/.tmuxp', extensions=['.yml', '.yaml', '.json', '.ini'])¶
Return a list of configs in config_dir.
参数: 返回类型: list
- static config.in_cwd()¶
Return list of configs in current working directory.
If filename is .tmuxp.py, .tmuxp.json, .tmuxp.yaml or .tmuxp.ini.
返回类型: list
Import and export¶
- static config.validate_schema(sconf)¶
Return True if config schema is correct.
参数: sconf (dict) – session configuration 返回类型: bool
- static config.expand(sconf, cwd=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/INI files into python dicts for you.
参数: - sconf (dict) – the configuration for the session
- cwd – directory to expand relative paths against. should be the dir of the config directory.
返回类型: dict
- static config.inline(sconf)¶
Return config in inline form, opposite of config.expand().
参数: sconf (dict) – unexpanded config file 返回类型: dict
- static 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.
参数: sconf (dict) – the session configuration 返回类型: dict
- static 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 参数: sconf (dict) – python dict for session configuration
- static config.import_tmuxinator(sconf)¶
Return tmuxp config from a tmuxinator yaml config.
参数: sconf (dict) – python dict for session configuration 返回类型: 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.
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 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.
参数: session (Session) – - session to build workspace in
Exceptions¶
- exception tmuxp.exc.TmuxpException¶
Base Exception for Tmuxp Errors.
- Also for Python 2.6 compat:
- http://stackoverflow.com/a/6029838
- exception tmuxp.exc.TmuxSessionExists¶
Session does not exist in the server.
- exception tmuxp.exc.EmptyConfigException¶
Configuration is empty.
- exception tmuxp.exc.ConfigError¶
Error parsing tmuxp configuration dict.