Python workspace internal API
tmuxp 1.74.0 · Source
tmuxp’s workspace APIs are internal implementation details with no stability
guarantee. They use libtmux’s Server, Session, Window, and Pane objects
for tmux control. Use the CLI guide to load workspace files.
Load and validate¶
tmuxp.workspace.loader.expand normalizes shorthand, variables, and paths.
loader.trickle applies inherited configuration after expansion. Both operate
on workspace dictionaries. validation.validate_schema checks required
structure; it is not a complete machine-readable schema of every runtime
behavior.
Consult the upstream loader API and validation API for parameter and error details.
Build and extend¶
tmuxp.workspace.builder.WorkspaceBuilder is the compatibility alias for
ClassicWorkspaceBuilder. Construct it with expanded session_config and a
libtmux server, call build, then read ClassicWorkspaceBuilder.session.
WorkspaceBuilderProtocol defines the interface used by the CLI, including
construction callbacks, building into an optional existing session, and
session discovery. The registry resolves named entry points or import paths.
Use the upstream builder API
and custom builder guide
when implementing an extension.
Export and CLI¶
tmuxp.workspace.freezer.freeze(session) reads a live session into a
configuration dictionary. freezer.inline compacts that expanded structure
for a file. The freezer API
documents both operations.
The CLI reference covers loading, freezing, listing, searching, editing, importing, and converting workspaces. These are application commands, separate from the language-level workspace builder.
API declarations
Follow a declaration for its signature, members, documentation, and source.
Workspace files
tmuxp.workspace.loader.expand- Resolve workspace variables and expand shorthand style / inline properties.
tmuxp.workspace.loader.expand_cmd- Resolve shell variables and expand shorthands in a tmuxp config mapping.
tmuxp.workspace.loader.expandshell- Resolve shell variables based on user's $HOME and env.
tmuxp.workspace.finders.find_local_workspace_files- Find .tmuxp.* files by traversing upward from start directory.
tmuxp.workspace.finders.find_workspace_file- Return the real config path or raise an exception.
tmuxp.workspace.finders.get_workspace_dir- Return tmuxp workspace directory.
tmuxp.workspace.finders.get_workspace_dir_candidates- Return all candidate workspace directories with existence status.
tmuxp.workspace.importers.import_teamocil- Return tmuxp workspace from a teamocil__ YAML workspace.
tmuxp.workspace.importers.import_tmuxinator- Return tmuxp workspace from a tmuxinator__ YAML workspace.
tmuxp.workspace.finders.in_cwd- Return list of workspace_files in current working directory.
tmuxp.workspace.finders.in_dir- Return a list of workspace_files in workspace_dir.
tmuxp.workspace.finders.is_pure_name- Return True if path is a name and not a file path.
tmuxp.workspace.finders.is_workspace_file- Return True if file has a valid workspace file type.
tmuxp.workspace.finders.LOCAL_WORKSPACE_FILEStmuxp.workspace.options.PaneReadiness- Policy for whether the builder waits for a pane's shell prompt.
tmuxp.workspace.options.resolve_session_shell- Resolve the effective interactive shell for a tmux session.
tmuxp.workspace.options.shell_is_zsh- Return True when shell names the zsh shell.
tmuxp.workspace.loader.trickle- Return a dict with "trickled down" / inherited workspace values.
tmuxp.workspace.constants.VALID_WORKSPACE_DIR_FILE_EXTENSIONStmuxp.workspace.validation.validate_schema- Return True if workspace schema is correct.
Building and freezing
tmuxp.workspace.builder.available_builders- Return the names of builders registered via entry points.
tmuxp.workspace.builder.ClassicWorkspaceBuilder- Load workspace from workspace dict object.
tmuxp.workspace.builder.classic.COLUMNS_FALLBACKtmuxp.workspace.freezer.freeze- Freeze live tmux session into a tmuxp workspace.
tmuxp.workspace.builder.get_default_columns- Return default session column size use when building new tmux sessions.
tmuxp.workspace.builder.get_default_rows- Return default session row size use when building new tmux sessions.
tmuxp.workspace.freezer.inline- Return workspace with inlined shorthands.
tmuxp.workspace.builder.prepended_sys_path- Temporarily prepend directories to sys.path, restoring it on exit.
tmuxp.workspace.builder.resolve_builder_class- Resolve the workspace builder class selected by session_config.
tmuxp.workspace.builder.resolve_builder_paths- Resolve and validate trusted workspace_builder_paths import roots.
tmuxp.workspace.builder.classic.ROWS_FALLBACKtmuxp.util.run_before_script- Execute shell script, streaming output to callback or terminal (if TTY).
tmuxp.workspace.builder.WORKSPACE_BUILDERS_GROUP- Entry-point group packaged builders register under.
tmuxp.workspace.builder.WorkspaceBuildertmuxp.workspace.options.WorkspaceBuilderOptions- Parsed workspace_builder_options catalog.
tmuxp.workspace.builder.WorkspaceBuilderProtocol- Contract a builder must satisfy to be driven by tmuxp load.
Command line
tmuxp.cli.cli- Manage tmux sessions.
tmuxp.cli.CLI_DESCRIPTIONtmuxp.cli.debug_info.CLIDebugInfoNamespace- Typed argparse.Namespace for tmuxp debug-info command.
tmuxp.cli.freeze.CLIFreezeNamespace- Typed argparse.Namespace for tmuxp freeze command.
tmuxp.cli.load.CLILoadNamespace- Typed argparse.Namespace for tmuxp load command.
tmuxp.cli.ls.CLILsNamespace- Typed argparse.Namespace for tmuxp ls command.
tmuxp.cli.CLINamespace- Typed argparse.Namespace for tmuxp root-level CLI.
tmuxp.cli.search.CLISearchNamespace- Typed argparse.Namespace for tmuxp search command.
tmuxp.cli.shell.CLIShellNamespace- Typed argparse.Namespace for tmuxp shell command.
tmuxp.cli.convert.command_convert- Entrypoint for tmuxp convert convert a tmuxp config between JSON and YAML.
tmuxp.cli.debug_info.command_debug_info- Entrypoint for tmuxp debug-info to print debug info to submit with issues.
tmuxp.cli.edit.command_edit- Entrypoint for tmuxp edit, open tmuxp workspace file in system editor.
tmuxp.cli.freeze.command_freeze- Entrypoint for tmuxp freeze, snapshot a tmux session into a tmuxp workspace.
tmuxp.cli.import_config.command_import- Import a teamocil/tmuxinator config.
tmuxp.cli.import_config.command_import_teamocil- Entrypoint for tmuxp import teamocil subcommand.
tmuxp.cli.import_config.command_import_tmuxinator- Entrypoint for tmuxp import tmuxinator subcommand.
tmuxp.cli.load.command_load- Load a tmux workspace from each WORKSPACE_FILE.
tmuxp.cli.ls.command_ls- Entrypoint for tmuxp ls subcommand.
tmuxp.cli.search.command_search- Entrypoint for tmuxp search subcommand.
tmuxp.cli.shell.command_shell- Entrypoint for tmuxp shell for tmux server, session, window and pane.
tmuxp.cli.search.compile_search_patterns- Compile search tokens into regex patterns.
tmuxp.cli.convert.CONVERT_DESCRIPTIONtmuxp.cli.convert.create_convert_subparser- Augment argparse.ArgumentParser with convert subcommand.
tmuxp.cli.debug_info.create_debug_info_subparser- Augment argparse.ArgumentParser with debug-info subcommand.
tmuxp.cli.edit.create_edit_subparser- Augment argparse.ArgumentParser with edit subcommand.
tmuxp.cli.freeze.create_freeze_subparser- Augment argparse.ArgumentParser with freeze subcommand.
tmuxp.cli.import_config.create_import_subparser- Augment argparse.ArgumentParser with import subparser.
tmuxp.cli.load.create_load_subparser- Augment argparse.ArgumentParser with load subcommand.
tmuxp.cli.ls.create_ls_subparser- Augment argparse.ArgumentParser with ls subcommand.
tmuxp.cli.create_parser- Create CLI argparse.ArgumentParser for tmuxp.
tmuxp.cli.search.create_search_subparser- Augment argparse.ArgumentParser with search subcommand.
tmuxp.cli.shell.create_shell_subparser- Augment argparse.ArgumentParser with shell subcommand.
tmuxp.cli.debug_info.DEBUG_INFO_DESCRIPTIONtmuxp.cli.search.DEFAULT_FIELDStmuxp.cli.edit.EDIT_DESCRIPTIONtmuxp.cli.search.evaluate_match- Evaluate if workspace fields match search patterns.
tmuxp.cli.search.extract_workspace_fields- Extract searchable fields from a workspace file.
tmuxp.cli.search.FIELD_ALIASEStmuxp.cli.search.find_search_matches- Find workspaces matching search patterns.
tmuxp.cli.freeze.FREEZE_DESCRIPTIONtmuxp.cli.import_config.get_teamocil_dir- Return teamocil configuration directory.
tmuxp.cli.import_config.get_tmuxinator_dir- Return tmuxinator configuration directory.
tmuxp.cli.search.highlight_matches- Highlight regex matches in text.
tmuxp.cli.import_config.import_config- Import a configuration from a workspace_file.
tmuxp.cli.import_config.IMPORT_DESCRIPTIONtmuxp.cli.import_config.ImportConfigFn- Typing for import configuration callback function.
tmuxp.cli.load.LOAD_DESCRIPTIONtmuxp.cli.load.load_plugins- Load and return plugins in workspace.
tmuxp.cli.load.load_workspace- Entrypoint for tmuxp load, load a tmuxp "workspace" session via config file.
tmuxp.cli.ls.LS_DESCRIPTIONtmuxp.cli.search.normalize_fields- Normalize field names using aliases.
tmuxp.cli.nstmuxp.cli.search.parse_query_terms- Parse query terms into search tokens.
tmuxp.cli.utils.prompt- Return user input from command line.
tmuxp.cli.utils.prompt_bool- Return True / False by prompting user input from command line.
tmuxp.cli.utils.prompt_choices- Return user input from command line from set of provided choices.
tmuxp.cli.utils.prompt_yes_no- prompt_bool() returning yes by default.
tmuxp.cli.search.SEARCH_DESCRIPTIONtmuxp.cli.search.SearchPattern- Compiled search pattern with regex and metadata.
tmuxp.cli.search.SearchToken- Parsed search token with target fields and raw pattern.
tmuxp.cli.shell.SHELL_DESCRIPTIONtmuxp.cli.startup- Initialize CLI.
tmuxp.cli.debug_info.tmuxp_pathtmuxp.cli.search.VALID_FIELDStmuxp.cli.search.WorkspaceFields- Extracted searchable fields from a workspace file.
tmuxp.cli.ls.WorkspaceInfo- Workspace file information for JSON output.
tmuxp.cli.search.WorkspaceSearchResult- Search result for a workspace that matched.
Plugins and shell
tmuxp.plugin.Config- tmuxp plugin configuration mapping.
tmuxp.plugin.DEFAULT_CONFIGtmuxp.shell.detect_best_shell- Return the best, most feature-rich shell available.
tmuxp.shell.get_bpython- Return bpython shell.
tmuxp.shell.get_code- Launch basic python shell via code.
tmuxp.shell.get_ipython- Return ipython shell.
tmuxp.shell.get_ipython_arguments- Return ipython shell args via IPYTHON_ARGUMENTS environment variables.
tmuxp.shell.get_launch_args- Return tmuxp shell launch arguments, counting for overrides.
tmuxp.shell.get_ptipython- Based on django-extensions.
tmuxp.shell.get_ptpython- Return ptpython shell.
tmuxp.shell.has_bpython- Return True if bpython is installed.
tmuxp.shell.has_ipython- Return True if ipython is installed.
tmuxp.shell.has_ptipython- Return True if ptpython + ipython are both installed.
tmuxp.shell.has_ptpython- Return True if ptpython is installed.
tmuxp.shell.launch- Launch interactive libtmux shell for tmuxp shell.
tmuxp.plugin.LIBTMUX_MAX_VERSIONtmuxp.plugin.LIBTMUX_MIN_VERSIONtmuxp.plugin.setup_plugin_config- Initialize tmuxp plugin configuration.
tmuxp.plugin.TMUX_MAX_VERSIONtmuxp.plugin.TMUX_MIN_VERSIONtmuxp.plugin.TMUXP_MAX_VERSIONtmuxp.plugin.TMUXP_MIN_VERSIONtmuxp.log.TmuxpLoggerAdapter- LoggerAdapter that merges extra dictionary on Python < 3.13.
tmuxp.plugin.TmuxpPlugin- Base class for a tmuxp plugin.
tmuxp.plugin.validate_plugin_config- Return True if tmuxp plugin configuration valid, also upcasts.
Errors
tmuxp.exc.ActiveSessionMissingWorkspaceException- Active session cannot be found while loading tmuxp workspace.
tmuxp.exc.BeforeLoadScriptError- Shell script execution error.
tmuxp.exc.BeforeLoadScriptNotExists- Raises if shell script could not be found.
tmuxp.cli.convert.ConvertUnknownFileType- Raise if tmuxp convert encounters an unknown filetype.
tmuxp.exc.EmptyWorkspaceException- Workspace file is empty.
tmuxp.cli.search.InvalidFieldError- Raised when an invalid field name is specified.
tmuxp.workspace.validation.InvalidPluginsValidationError- Tmuxp configuration error for invalid plugins.
tmuxp.exc.InvalidWorkspaceBuilder- Resolved workspace_builder object is not a usable builder.
tmuxp.exc.InvalidWorkspaceBuilderOption- A workspace_builder_options value is invalid.
tmuxp.exc.PaneNotFound- tmux pane not found.
tmuxp.workspace.validation.SchemaValidationError- Tmuxp configuration validation base error.
tmuxp.exc.SessionMissingWorkspaceException- Session missing while loading tmuxp workspace.
tmuxp.workspace.validation.SessionNameMissingValidationError- Tmuxp configuration error for session name missing.
tmuxp.exc.SessionNotFound- tmux session not found.
tmuxp.exc.TmuxpException- Base Exception for Tmuxp Errors.
tmuxp.exc.TmuxpPluginException- Base Exception for Tmuxp Errors.
tmuxp.workspace.validation.WindowListMissingValidationError- Tmuxp configuration error for window list missing.
tmuxp.workspace.validation.WindowNameMissingValidationError- Tmuxp configuration error for missing window_name.
tmuxp.exc.WindowNotFound- tmux window not found.
tmuxp.exc.WorkspaceBuilderError- Base error for resolving and validating a workspace builder.
tmuxp.exc.WorkspaceBuilderImportError- Configured workspace_builder failed to import.
tmuxp.exc.WorkspaceBuilderNotFound- Configured workspace_builder could not be resolved.
tmuxp.exc.WorkspaceBuilderPathError- A workspace_builder_paths entry is not a usable directory.
tmuxp.exc.WorkspaceError- Error parsing tmuxp workspace data.
Utilities
tmuxp.log.debug_log_template- Return the prefix for the log message. Template for Formatter.
tmuxp.log.DebugLogFormatter- Provides greater technical details than standard log Formatter.
tmuxp.util.get_current_pane- Return Pane if one found in env.
tmuxp.util.get_pane- Get tmux pane for server by pane name, respects current pane, if passed.
tmuxp.util.get_session- Get tmux session for server by session name, respects current pane, if passed.
tmuxp.util.get_window- Get tmux window for server by window name, respects current pane, if passed.
tmuxp.log.LEVEL_COLORStmuxp.log.LogFormatter- Format logs for tmuxp.
tmuxp.util.oh_my_zsh_auto_title- Give warning and offer to fix DISABLE_AUTO_TITLE.
tmuxp.util.PY2tmuxp.log.set_style- Stylize terminal logging output.
tmuxp.log.setup_log_file- Attach a file handler to the tmuxp logger.
tmuxp.cli.setup_logger- Configure tmuxp's logging for CLI use.
tmuxp.types.StrPath- os.PathLike or str
tmuxp.log.tmuxp_echo- Print user-facing CLI output.