Finders - tmuxp.workspace.finders

Workspace (configuration file) finders for tmuxp.

tmuxp.workspace.finders.LOCAL_WORKSPACE_FILES = ['.tmuxp.yaml', '.tmuxp.yml', '.tmuxp.json']

Local workspace file names (dotfiles in project directories)

tmuxp.workspace.finders.is_workspace_file(filename, extensions=None)

Return True if file has a valid workspace file type.

Return type:

bool

Parameters:

• filename (str) – filename to check (e.g. mysession.json).

• extensions (str or list) – filetypes to check (e.g. ['.yaml', '.json']).

Return type:

bool

tmuxp.workspace.finders.in_dir(workspace_dir=None, extensions=None)

Return a list of workspace_files in workspace_dir.

Return type:

list[str]

Parameters:

• workspace_dir (str) – directory to search

• extensions (list) – filetypes to check (e.g. ['.yaml', '.json']).

Return type:

list

tmuxp.workspace.finders.in_cwd()

Return list of workspace_files in current working directory.

If filename is .tmuxp.py, .tmuxp.json, .tmuxp.yaml.

Return type:

list[str]

Returns:

workspace_files in current working directory

Return type:

list

Examples

>>> sorted(in_cwd())
['.tmuxp.json', '.tmuxp.yaml']

tmuxp.workspace.finders.find_local_workspace_files(start_dir=None, *, stop_at_home=True)

Find .tmuxp.* files by traversing upward from start directory.

Searches the start directory and all parent directories up to (but not past): - User home directory (when stop_at_home=True) - Filesystem root

Return type:

list[Path]

Parameters:

• start_dir (pathlib.Path | str | None) – Directory to start searching from. Defaults to current working directory.

• stop_at_home (bool) – If True, stops traversal at user home directory. Default True.

Returns:

List of workspace file paths found, ordered from closest to farthest.

Return type:

list[pathlib.Path]

Examples

>>> import tempfile
>>> import pathlib
>>> with tempfile.TemporaryDirectory() as tmpdir:
...     home = pathlib.Path(tmpdir)
...     project = home / "project"
...     project.mkdir()
...     _ = (project / ".tmuxp.yaml").write_text("session_name: test")
...     # Would find .tmuxp.yaml in project dir
...     len(find_local_workspace_files(project, stop_at_home=False)) >= 0
True

tmuxp.workspace.finders.get_workspace_dir()

Return tmuxp workspace directory.

TMUXP_CONFIGDIR environmental variable has precedence if set. We also evaluate XDG default directory from XDG_CONFIG_HOME environmental variable if set or its default. Then the old default ~/.tmuxp is returned for compatibility.

Return type:

str

Returns:

absolute path to tmuxp config directory

Return type:

str

tmuxp.workspace.finders.get_workspace_dir_candidates()

Return all candidate workspace directories with existence status.

Returns a list of all directories that tmuxp checks for workspaces, in priority order, with metadata about each.

The priority order is: 1. TMUXP_CONFIGDIR environment variable (if set) 2. XDG_CONFIG_HOME/tmuxp (if XDG_CONFIG_HOME set) OR ~/.config/tmuxp/ 3. ~/.tmuxp (legacy default)

Return type:

list[dict[str, Any]]

Returns:

List of dicts with: - path: str (privacy-masked via PrivatePath) - source: str (e.g., “$TMUXP_CONFIGDIR”, “$XDG_CONFIG_HOME/tmuxp”, “Legacy”) - exists: bool - workspace_count: int (0 if not exists) - active: bool (True if this is the directory get_workspace_dir() returns)

Return type:

list[dict[str, Any]]

Examples

>>> candidates = get_workspace_dir_candidates()
>>> isinstance(candidates, list)
True
>>> all('path' in c and 'exists' in c for c in candidates)
True

tmuxp.workspace.finders.find_workspace_file(workspace_file, workspace_dir=None)

Return the real config path or raise an exception.

If workspace file is directory, scan for .tmuxp.{yaml,yml,json} in directory. If one or more found, it will warn and pick the first.

If workspace file is “.”, “./” or None, it will scan current directory.

If workspace file is has no path and only a filename, e.g. “my_workspace.yaml” it will search workspace dir.

If workspace file has no path and no extension, e.g. “my_workspace”, it will scan for file name with yaml, yml and json. If multiple exist, it will warn and pick the first.

Return type:

str

Parameters:

workspace_file (str) –

Workspace file, valid examples:

• a file name, my_workspace.yaml

• relative path, ../my_workspace.yaml or ../project

• a period, .

Returns:

Resolved absolute path to workspace file.

Return type:

str

Raises:

FileNotFoundError – If workspace file cannot be found.

tmuxp.workspace.finders.is_pure_name(path)

Return True if path is a name and not a file path.

Return type:

bool

Parameters:

path (str) – Path (can be absolute, relative, etc.)

Returns:

True if path is a name of workspace in workspace dir, not file path.

Return type:

bool