Builder registry - tmuxp.workspace.builder.registry

Resolve and sandbox workspace builders selected by a workspace config.

A workspace may point tmuxp at a builder other than the classic tmuxp.workspace.builder.classic.ClassicWorkspaceBuilder via the workspace_builder key (a Python dotted path, module:attr reference, or an entry-point name in the tmuxp.workspace_builders group). When the builder lives outside the active environment, workspace_builder_paths lists trusted directories that are temporarily added to sys.path for the import and build.

Security note: only literal directories are prepended to sys.path. This deliberately avoids site.addsitedir(), which executes .pth startup files and is broader than making a module importable. The trust boundary is the author of the workspace file.

tmuxp.workspace.builder.registry.WORKSPACE_BUILDERS_GROUP = 'tmuxp.workspace_builders'
data
data
tmuxp.workspace.builder.registry.WORKSPACE_BUILDERS_GROUP = 'tmuxp.workspace_builders'

Entry-point group packaged builders register under.

tmuxp.workspace.builder.registry.resolve_builder_paths(session_config, workspace_file=None)
function[source]
function[source]
tmuxp.workspace.builder.registry.resolve_builder_paths(session_config, workspace_file=None)

Resolve and validate trusted workspace_builder_paths import roots.

Each entry is shell-expanded (~ and $VARS), resolved relative to the workspace file’s directory when not absolute, and required to be an existing directory. Returns [] when the key is absent, so existing workspaces add nothing to sys.path.

Parameters:

  • session_config (dict) – the expanded workspace configuration

  • workspace_file (str or os.PathLike, optional) – path to the workspace file; its parent anchors relative entries

Return type:

list of pathlib.Path

Examples

Absent key resolves to an empty list (no-op for existing workspaces):

>>> resolve_builder_paths({}, None)
[]

An existing directory is resolved:

>>> root = tmp_path / "roots"
>>> root.mkdir()
>>> resolve_builder_paths({"workspace_builder_paths": [str(root)]}, None) == [
...     root.resolve()
... ]
True

A missing directory is rejected:

>>> resolve_builder_paths(
...     {"workspace_builder_paths": [str(tmp_path / "missing")]}, None
... )
Traceback (most recent call last):
...
tmuxp.exc.WorkspaceBuilderPathError: ...
tmuxp.workspace.builder.registry.prepended_sys_path(paths)
function[source]
function[source]
tmuxp.workspace.builder.registry.prepended_sys_path(paths)

Temporarily prepend directories to sys.path, restoring it on exit.

Paths are prepended in order (first entry ends up at sys.path[0]). An empty or falsy paths is a no-op. Uses only literal directory entries; it avoids site.addsitedir() (which runs .pth startup code).

Parameters:

paths (list of pathlib.Path or None) – directories to prepend

Return type:

Iterator[None]

Examples

>>> import sys
>>> ext = tmp_path / "ext"
>>> ext.mkdir()
>>> before = list(sys.path)
>>> with prepended_sys_path([ext]):
...     sys.path[0] == str(ext)
True
>>> sys.path == before
True
tmuxp.workspace.builder.registry.available_builders()
function[source]
function[source]
tmuxp.workspace.builder.registry.available_builders()

Return the names of builders registered via entry points.

Examples

>>> isinstance(available_builders(), list)
True
Return type:

list[str]

tmuxp.workspace.builder.registry._load_entry_point(name)
function[source]
function[source]
tmuxp.workspace.builder.registry._load_entry_point(name)

Load a builder registered under entry-point name, else None.

Examples

>>> _load_entry_point("definitely-not-a-registered-builder") is None
True
Parameters:

name (str)

Return type:

Any | None

tmuxp.workspace.builder.registry._import_target(target)
function[source]
function[source]
tmuxp.workspace.builder.registry._import_target(target)

Import an object from a module:attr or dotted module.attr path.

Examples

>>> _import_target(
...     "tmuxp.workspace.builder.classic:ClassicWorkspaceBuilder"
... ).__name__
'ClassicWorkspaceBuilder'

The historical tmuxp.workspace.builder:WorkspaceBuilder alias resolves to the same class:

>>> _import_target("tmuxp.workspace.builder:WorkspaceBuilder").__name__
'ClassicWorkspaceBuilder'
Parameters:

target (str)

Return type:

Any

tmuxp.workspace.builder.registry._validate_builder(obj, target)
function[source]
function[source]
tmuxp.workspace.builder.registry._validate_builder(obj, target)

Validate that obj is a usable workspace builder.

A class must expose a callable build method and a constructor accepting session_config, server, and plugins (or **kwargs) — the arguments tmuxp load always passes. Non-class callables (factories) are trusted and validated at instantiation.

Examples

>>> from tmuxp.workspace.builder.classic import ClassicWorkspaceBuilder
>>> _validate_builder(ClassicWorkspaceBuilder, "classic")

>>> _validate_builder(object, "object")
Traceback (most recent call last):
...
tmuxp.exc.InvalidWorkspaceBuilder: 'object' is not a valid workspace builder: ...
Parameters:
Return type:

None

tmuxp.workspace.builder.registry.resolve_builder_class(session_config)
function[source]
function[source]
tmuxp.workspace.builder.registry.resolve_builder_class(session_config)

Resolve the workspace builder class selected by session_config.

Resolution of the workspace_builder value:

  1. absent/empty → the classic ClassicWorkspaceBuilder (no import, no entry-point scan);

  2. contains : → a module:attr object reference;

  3. no . and no : → an entry-point name in the tmuxp.workspace_builders group;

  4. dotted, no : → an entry-point name if registered, otherwise a module.attr dotted path.

Parameters:

session_config (dict) – the expanded workspace configuration

Returns:

a workspace builder class (or builder factory) satisfying WorkspaceBuilderProtocol

Return type:

type

Examples

The default resolves to the classic builder without importing anything:

>>> from tmuxp.workspace.builder.classic import ClassicWorkspaceBuilder
>>> resolve_builder_class({}) is ClassicWorkspaceBuilder
True

A dotted module:attr reference is imported and validated:

>>> resolve_builder_class(
...     {
...         "workspace_builder": (
...             "tmuxp.workspace.builder.classic:ClassicWorkspaceBuilder"
...         )
...     }
... ) is ClassicWorkspaceBuilder
True