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: object

A tmux format that tmux expands, instead of storing it as typed.

Names, titles, start directories and file paths passed to libtmux as plain str are kept as typed. Wrap a format your program wrote in Format to have tmux expand it, as it does for #{...} in tmux.conf. Where tmux always expands an argument, such as display_message(), a Format is 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 + or join(), which keep it literal; place it inside an expression, such as a conditional or comparison, with escape(). 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 str is 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,'): ...