Skip to content

host_tools

host_tools

Find host executables from the caller's current absolute PATH entries.

This module uses only the standard library. Setup may copy its source into standalone programs without introducing an installed-package dependency.

__all__ = ['host_path', 'find_host_tool', 'require_host_tool', 'host_tools_source'] module-attribute

host_path(path=None)

Keep absolute search directories, without resolving symlinks or adding defaults.

None reads the current environment. An absent or explicitly empty PATH permits no name lookup; empty and relative entries never search the cwd.

Source code in src/terok_util/host_tools.py 
17
18
19
20
21
22
23
24
def host_path(path: str | None = None) -> str:
    """Keep absolute search directories, without resolving symlinks or adding defaults.

    ``None`` reads the current environment. An absent or explicitly empty PATH
    permits no name lookup; empty and relative entries never search the cwd.
    """
    path = os.environ.get("PATH", "") if path is None else path
    return os.pathsep.join(entry for entry in path.split(os.pathsep) if os.path.isabs(entry))

find_host_tool(name, *, path=None)

Find an executable by name or an explicitly supplied absolute path.

Relative paths containing a slash are rejected. Returned paths retain the spelling selected by PATH, including symlinks, and are never cached.

Source code in src/terok_util/host_tools.py 
27
28
29
30
31
32
33
34
35
def find_host_tool(name: str, *, path: str | None = None) -> str | None:
    """Find an executable by name or an explicitly supplied absolute path.

    Relative paths containing a slash are rejected. Returned paths retain the
    spelling selected by PATH, including symlinks, and are never cached.
    """
    if os.path.dirname(name) and not os.path.isabs(name):
        return None
    return shutil.which(name, path=host_path(path))

require_host_tool(name, *, path=None)

Find an executable or raise FileNotFoundError with the searched PATH.

Source code in src/terok_util/host_tools.py 
38
39
40
41
42
43
def require_host_tool(name: str, *, path: str | None = None) -> str:
    """Find an executable or raise ``FileNotFoundError`` with the searched PATH."""
    search_path = host_path(path)
    if executable := find_host_tool(name, path=search_path):
        return executable
    raise FileNotFoundError(f"Host executable {name!r} not found in PATH={search_path!r}")

host_tools_source()

Return the standalone module source for installation alongside hook scripts.

Source code in src/terok_util/host_tools.py 
46
47
48
def host_tools_source() -> str:
    """Return the standalone module source for installation alongside hook scripts."""
    return Path(__file__).read_text(encoding="utf-8")