env_all()

def env_all() -> dict

Returns all environment variables as a dictionary.

Captures a snapshot of all environment variables at the time of the call.

Non-UTF-8 keys or values are included with invalid bytes replaced by the Unicode replacement character (U+FFFD), consistent with the lossy conversion used by env_cwd() and env_path_list().

Returns

A dictionary mapping environment variable names (strings) to their values (strings). For example: {“PATH”: “/usr/bin:…”, “HOME”: “/home/user”, …}

env_chdir()

def env_chdir(path)

Changes the current working directory of the process.

Changes the working directory for the current process and any subsequently spawned child processes. Does not affect parent processes. Use env_cwd() to save the current directory before changing, so it can be restored later.

Raises: Error: If the directory does not exist or is not accessible

Args

• path: string: The directory path to change to. Can be absolute or relative. Supports both Unix-style ("/path/to/dir") and Windows-style (“C:\path\to\dir”) paths.

Returns

None

env_cwd()

def env_cwd() -> string

Returns the current working directory of the process.

Returns the absolute path to the directory the process is currently operating in. This is affected by env_chdir() calls.

Non-UTF-8 path components are replaced by the Unicode replacement character (U+FFFD) via lossy conversion.

Raises: Error: If the current directory cannot be determined (e.g., if it has been deleted)

Returns

An absolute path string to the current working directory.

env_get()

def env_get(name, default)

Gets an environment variable by name.

Returns None when the variable is absent and no default was provided, making it possible to distinguish “variable not set” from “variable set to empty string”. When a default is supplied, that value is returned instead of None for missing variables.

Use env_has() as a lighter-weight existence check when the value is not needed.

Raises: Error: If the environment variable contains invalid UTF-8 (rare)

Args

• name: string: The name of the environment variable (e.g., “PATH”, “HOME”, “USER”)
• default: Value to return when the variable is not set. When omitted, None is returned for missing variables.

Returns

The value of the environment variable as a string, the default value if the variable is not set and a default was given, or None if the variable is not set and no default was supplied.

env_has()

def env_has(name) -> bool

Checks whether an environment variable is present in the current process.

Returns True if the variable exists (even if its value is an empty string). This is useful for checking if a variable has been explicitly set without caring about its value.

Args

• name: string: The name of the environment variable to check

Returns

True if the variable is set in the environment, False otherwise

env_path_join()

def env_path_join(entries) -> string

Joins a list of directory paths into a PATH-style string.

Uses the platform separator (: on Unix/macOS, ; on Windows). This is the inverse of env_path_list(): use it to reconstruct PATH after modifying the list, without hard-coding platform-specific separators.

Raises: Error: If any entry contains the platform separator character.

Args

• entries: list: A list of directory path strings to join.

Returns

A single PATH-formatted string using the platform separator.

env_path_list()

def env_path_list() -> list

Splits the PATH environment variable into a list of directory entries.

Parses the system PATH variable and returns each directory as a separate element. Handles platform-specific path separators (: on Unix/macOS, ; on Windows). Returns an empty list if PATH is not set or is empty.

Non-UTF-8 path components are replaced by the Unicode replacement character (U+FFFD) via lossy conversion.

Returns

A list of directory paths in search order. Empty list if PATH is not set.

env_which()

def env_which(name) -> string

Finds the first executable matching the given name in PATH.

Searches through all directories in the PATH environment variable in order for an executable file with the given name. On Windows, also checks PATHEXT for recognized executable extensions (e.g., .COM, .EXE, .BAT, .CMD).

If the name contains path separators (/ or ), it is treated as a direct path and checked for executability rather than searching PATH.

Args

• name: string: The name of the executable to find (e.g., “git”, “python”, “node”) Can also be a relative path (e.g., “./script.sh” or “subdir/tool”)

Returns

The full absolute path to the executable if found, or empty string if not found.

env_which_all()

def env_which_all(name) -> list

Finds all executables matching the given name in PATH.

Searches through all directories in the PATH environment variable and returns all matching executables in PATH order. Useful for finding all versions of an interpreter, tool, or script. Handles platform-specific executable extensions and permissions. Duplicate paths are suppressed.

On Unix-like systems, only returns files with executable permissions. On Windows, returns files with recognized executable extensions from PATHEXT.

Args

• name: string: The name of the executable to find (e.g., “python”, “git”, “node”)

Returns

A list of full absolute paths to all matching executables in PATH order. Returns empty list if no matches found.