path_absolute()

def path_absolute(filepath) -> string

Convert a relative path to absolute.

Makes a path absolute by resolving it relative to the current working directory. Absolute paths are returned unchanged. Does NOT resolve symbolic links (use path_canonicalize for that).

Raises: Error: If the current working directory cannot be determined

Args

• filepath: string: The path to make absolute

Returns

str: The absolute path

path_basename()

def path_basename(filepath) -> string

Extract the final path component (filename).

Returns the last component of a path (the filename), excluding any directory parts.

Raises: Error: If path extraction fails

Args

• filepath: string: The file path to extract the filename from

Returns

str: The filename (final path component)

path_canonicalize()

def path_canonicalize(filepath) -> string

Canonicalize a path (resolve symlinks and normalize).

Performs full path resolution by:

1. Resolving symbolic links
2. Removing all . and .. components
3. Normalizing separators
4. Resolving to absolute path

The path must exist on the filesystem. Use path_normalize() for paths that might not exist, or path_absolute() for non-existent paths.

Raises: Error: If the path doesn’t exist or cannot be read

Args

• filepath: string: The path to canonicalize (must exist)

Returns

str: The canonical absolute path

path_components()

def path_components(filepath) -> list

Split a path into normalized components.

Returns a list of individual path components, with special handling for:

• Root directories (/)
• Parent directory references (..)
• Windows drive prefixes

Useful for analyzing path structure or reconstructing paths.

Args

• filepath: string: The path to decompose

Returns

list: A list of path components as strings

path_dirname()

def path_dirname(filepath) -> string

Extract the directory portion of a path.

Returns the parent directory path without the final filename component. Useful for getting the folder containing a file.

Raises: Error: If path extraction fails

Args

• filepath: string: The file path to extract the directory from

Returns

str: The directory portion of the path (empty string if no parent exists)

path_expand_user()

def path_expand_user(filepath) -> string

Expand ~ to the user’s home directory.

Replaces the leading ~ in a path with the user’s home directory path. Handles both ~ alone and ~/… patterns.

Raises: Error: If the home directory cannot be determined

Args

• filepath: string: The path with potential ~ to expand

Returns

str: The path with ~ expanded to home directory

path_expand_vars()

def path_expand_vars(filepath) -> string

Expand environment variables in a path.

Replaces $VAR and ${VAR} tokens in the path with their environment variable values. Useful for paths that depend on system configuration.

Args

• filepath: string: The path with potential environment variables to expand

Returns

str: The path with environment variables substituted

path_extension()

def path_extension(filepath) -> string

Extract the file extension without the dot.

Returns the file extension (final component after the last dot), without including the dot itself. Returns empty string if no extension exists.

Raises: Error: If extension extraction fails

Args

• filepath: string: The file path to extract the extension from

Returns

str: The file extension without the dot (empty if no extension)

path_is_absolute()

def path_is_absolute(filepath) -> bool

Check if a path is absolute (not relative).

Determines whether a path is absolute (starting from the root) or relative to the current directory. Handles both Unix-style and Windows-style paths.

Args

• filepath: string: The path to check

Returns

bool: True if the path is absolute, False if relative

path_join()

def path_join(parts) -> string

Join path segments using the platform separator.

Intelligently combines multiple path components into a single path string, using the appropriate separator for the current platform (/ on Unix, \ on Windows).

Raises: Error: If path joining fails

Args

• parts: list: A list of path segments to join (empty strings are handled gracefully)

Returns

str: The joined path using the platform separator

path_normalize()

def path_normalize(filepath) -> string

Normalize a path lexically (without filesystem access).

Cleans up path representation by collapsing:

• Repeated separators (// becomes /)
• Current directory references (. is removed)
• Parent directory references (..) where possible

This is purely lexical normalization - it does NOT access the filesystem or resolve symbolic links. Use path_canonicalize() for full resolution.

Raises: Error: If normalization fails

Args

• filepath: string: The path to normalize

Returns

str: The normalized path

path_parent()

def path_parent(filepath, levels) -> string

Get the parent directory, optionally multiple levels up.

Returns the nth parent directory by traversing up the path n times. Returns empty string if there are no more parents.

Raises: Error: If path traversal fails

Args

• filepath: string: The path to get the parent of
• levels: int: Number of parent directory levels to go up (default: 1)

Returns

str: The parent path, or empty string if no more parents exist

path_relative_to()

def path_relative_to(target_path, base_path) -> string

Compute a relative path from base to target.

Creates a relative path that, when resolved from base_path, would reach target_path. Useful for creating relative links or displaying user-friendly path relationships.

Raises: Error: If relative path cannot be computed

Args

• target_path: string: The destination path
• base_path: string: The starting path (typically a directory)

Returns

str: The relative path from base to target

path_separator()

def path_separator() -> string

Get the platform path separator.

Returns the character used to separate path components on the current platform: “/” on Unix/macOS/Linux, “" on Windows.

Returns

str: The path separator (”/" or “")

path_split()

def path_split(filepath) -> tuple

Split a path into directory and filename components.

Separates a path into its parent directory and final filename in one operation. Equivalent to calling (path_dirname(), path_basename()) but more efficient.

Raises: Error: If path splitting fails

Args

• filepath: string: The file path to split

Returns

tuple: A (directory, filename) tuple

path_stem()

def path_stem(filepath) -> string

Extract the file stem (filename without extension).

Returns the filename without its final extension. For files with multiple dots, only the last extension is removed (e.g., “archive.tar.gz” -> “archive.tar”).

Raises: Error: If stem extraction fails

Args

• filepath: string: The file path to extract the stem from

Returns

str: The filename without the final extension

path_with_extension()

def path_with_extension(filepath, new_ext) -> string

Replace or add a file extension.

Creates a new path with a different extension, replacing any existing extension or adding one if the file has none.

Raises: Error: If the operation fails

Args

• filepath: string: The original file path
• new_ext: string: The new extension (without the dot; dot will be added automatically)

Returns

str: The path with the new extension