Options - tmuxp.workspace.options

Behavior options for tmuxp workspace builders.

The workspace_builder_options config catalog holds settings that tune how a workspace builder runs, independent of which builder is selected. It is a sibling to the tmux options / global_options / environment catalogs and is the home for builder-behavior knobs (today: pane readiness; later: parallel/async builder settings).

Example

workspace_builder_options:
  pane_readiness: auto   # auto | always | never (+ truthy/falsy aliases)

class tmuxp.workspace.options.PaneReadiness

class

class

class tmuxp.workspace.options.PaneReadiness

Bases: Enum

Policy for whether the builder waits for a pane’s shell prompt.

tmuxp waits for each default-shell pane to draw its prompt before dispatching layout and commands, which avoids a zsh prompt-redraw artifact (see tmuxp.workspace.builder.classic._wait_for_pane_ready()). The wait is only needed for zsh, so the default AUTO policy waits only when the session’s interactive shell is zsh.

AUTO = 'auto'

attribute

attribute

AUTO = 'auto'

ALWAYS = 'always'

attribute

attribute

ALWAYS = 'always'

NEVER = 'never'

attribute

attribute

NEVER = 'never'

classmethod from_config(value)

classmethod method

classmethod method

classmethod from_config(value)

Parse a pane_readiness config value into a policy.

Accepts the canonical auto / always / never strings, plus the truthy/falsy aliases users expect from boolean-like config keys.

Parameters:

value (Any) – value from workspace_builder_options.pane_readiness; None (key absent) resolves to AUTO

Return type:

PaneReadiness

Examples

>>> PaneReadiness.from_config(None) is PaneReadiness.AUTO
True
>>> PaneReadiness.from_config("auto") is PaneReadiness.AUTO
True
>>> PaneReadiness.from_config(True) is PaneReadiness.ALWAYS
True
>>> PaneReadiness.from_config("on") is PaneReadiness.ALWAYS
True
>>> PaneReadiness.from_config(1) is PaneReadiness.ALWAYS
True
>>> PaneReadiness.from_config(False) is PaneReadiness.NEVER
True
>>> PaneReadiness.from_config("never") is PaneReadiness.NEVER
True

Unknown values raise an actionable error:

>>> PaneReadiness.from_config("sometimes")
Traceback (most recent call last):
...
ValueError: invalid pane_readiness value: 'sometimes'; expected one of:
auto, always/true/on/yes/1, never/false/off/no/0

class tmuxp.workspace.options.WorkspaceBuilderOptions

class

class

class tmuxp.workspace.options.WorkspaceBuilderOptions

Bases: object

Parsed workspace_builder_options catalog.

An absent workspace_builder_options catalog uses the defaults, whose PaneReadiness.AUTO policy waits for a pane’s prompt only when the session shell is zsh: zsh workspaces build as before, while bash, sh, and other shells skip the wait. Set pane_readiness: always to restore the previous wait-everywhere behavior.

pane_readiness: PaneReadiness = 'auto'

attribute

attribute

pane_readiness: PaneReadiness = 'auto'

pane-prompt wait policy; defaults to PaneReadiness.AUTO

classmethod from_config(session_config)

classmethod method

classmethod method

classmethod from_config(session_config)

Build options from a full workspace session_config dict.

Reads the optional workspace_builder_options catalog; an absent or empty catalog yields the defaults (see the class docstring for how the default PaneReadiness.AUTO policy affects non-zsh shells).

Parameters:

session_config (dict) – the expanded workspace configuration

Return type:

WorkspaceBuilderOptions

Examples

>>> WorkspaceBuilderOptions.from_config({}).pane_readiness
<PaneReadiness.AUTO: 'auto'>

>>> cfg = {"workspace_builder_options": {"pane_readiness": "always"}}
>>> WorkspaceBuilderOptions.from_config(cfg).pane_readiness
<PaneReadiness.ALWAYS: 'always'>

__init__(pane_readiness=PaneReadiness.AUTO)

method

method

__init__(pane_readiness=PaneReadiness.AUTO)

Parameters:

pane_readiness (PaneReadiness)

Return type:

None

tmuxp.workspace.options.shell_is_zsh(shell)

function

function

tmuxp.workspace.options.shell_is_zsh(shell)

Return True when shell names the zsh shell.

Parameters:

shell (str or None) – a shell path or name (e.g. /usr/bin/zsh)

Return type:

bool

Examples

>>> shell_is_zsh("/usr/bin/zsh")
True
>>> shell_is_zsh("/bin/bash")
False
>>> shell_is_zsh(None)
False

tmuxp.workspace.options.resolve_session_shell(session, env=None)

function

function

tmuxp.workspace.options.resolve_session_shell(session, env=None)

Resolve the effective interactive shell for a tmux session.

Prefers tmux’s default-shell option (which reflects a workspace’s options.default-shell once applied, otherwise tmux’s global default), and falls back to the SHELL environment variable.

Parameters:

• session (libtmux.Session) – live session exposing show_option("default-shell")

• env (Mapping, optional) – environment mapping for the SHELL fallback; defaults to os.environ

Returns:

resolved shell path/name, or "" when undeterminable

Return type:

str

Examples

>>> class FakeSession:
...     def __init__(self, shell):
...         self._shell = shell
...     def show_option(self, name, **kwargs):
...         return self._shell

The tmux default-shell wins when set:

>>> resolve_session_shell(FakeSession("/usr/bin/zsh"), env={})
'/usr/bin/zsh'

The SHELL env var is the fallback:

>>> resolve_session_shell(FakeSession(None), env={"SHELL": "/bin/bash"})
'/bin/bash'