Formats¶
Plain strings passed to libtmux are kept as typed; Format
marks a value for tmux to expand. See Literal text and tmux formats for a guide.
-
class libtmux.Format¶class libtmux.Format¶
Bases:
objectA tmux format that tmux expands, instead of storing it as typed.
Names, titles, start directories and file paths passed to libtmux as plain
strare kept as typed. Wrap a format your program wrote inFormatto have tmux expand it, as it does for#{...}intmux.conf. Where tmux always expands an argument, such asdisplay_message(), aFormatis accepted too, so text from users or files can be combined with it safely.Only pass text your program wrote. Add text from users or files with
+orjoin(), which keep it literal; place it inside an expression, such as a conditional or comparison, withescape(). Never place it inside#(...), which runs a shell command.- Parameters:
template (
str) – The format, in tmux’s own syntax, for example"#{pane_current_path}".
Examples
Open a pane in the directory of the session’s active pane:
>>> pane.split(start_directory=Format("#{pane_current_path}")) Pane(...)
Name a window after its session, with user text kept literal:
>>> user_text = "x#S" >>> window.rename_window(Format("#{session_name}-") + user_text) Window(...) >>> window.window_name == f"{session.session_name}-x#S" True
A plain
stris never expanded:>>> window.rename_window("#{session_name}") Window(...) >>> window.window_name '#{session_name}'
Plain text cannot be added where tmux would read it as format syntax:
>>> Format("#{?pane_active,") + "yes" Traceback (most recent call last): ... ValueError: cannot add plain text to Format('#{?pane_active,'): ...