fs_append_text()

def fs_append_text(path, content) -> NoneType

Append text content to the end of a file.

If the file does not exist, it will be created. This is useful for building up log files or accumulating data.

Raises: Error: If the file cannot be created or written

Args

• path: string: Path to the file
• content: string: Text content to append

Returns

None

fs_chmod()

def fs_chmod(path, spec) -> NoneType

Change file permissions using symbolic notation (Unix-like).

Supports specification like “u+rx”, “g-w”, “a=r”, etc. Only available on Unix-like systems.

Raises: Error: If spec is invalid or permissions cannot be set

Args

• path: string: Path to the file
• spec: string: Chmod specification as string ([ugoa][+-=][rwx]+), e.g., “u+x”, “u+rx”, “a-w”

Returns

None

fs_chown()

def fs_chown(path, user, group) -> NoneType

Change file ownership (Unix-like systems only).

Raises: Error: If user/group don’t exist or chown fails

Args

• path: string: Path to the file
• user: string: Username to set as owner
• group: string: Group name to set as group owner

Returns

None

fs_copy()

def fs_copy(src, dst, recursive, overwrite, follow_symlinks) -> NoneType

Copy a file or directory to a destination.

Raises: Error: If source is directory but recursive=False, or if copy fails

Args

• src: string: Source path (file or directory)
• dst: string: Destination path
• recursive: bool: If True, recursively copy directories (required for directories)
• overwrite: bool: If True, overwrite destination if it exists
• follow_symlinks: bool: If True, follow symlinks; if False, copy the link itself

Returns

None

fs_exists()

def fs_exists(path) -> bool

Check if a file or directory exists.

Args

• path: string: Path to check

Returns

bool: True if the path exists, False otherwise

fs_is_directory()

def fs_is_directory(path) -> bool

Check if a path is a directory.

Args

• path: string: Path to check

Returns

bool: True if the path is a directory, False otherwise

fs_is_file()

def fs_is_file(path) -> bool

Check if a path is a regular file.

Args

• path: string: Path to check

Returns

bool: True if the path is a regular file, False otherwise

fs_is_symlink()

def fs_is_symlink(path) -> bool

Check if a path is a symbolic link.

Args

• path: string: Path to check

Returns

bool: True if the path is a symbolic link, False otherwise

fs_is_text_file()

def fs_is_text_file(path) -> bool

Check if a file is a text file (vs binary).

Raises: Error: If the path is not a file or cannot be read

Args

• path: string: Path to the file

Returns

bool: True if the file appears to be text, False if binary

fs_metadata()

def fs_metadata(path) -> dict

Get metadata about a file or directory.

Returns a dictionary with file information including size, timestamps, type, and permissions.

Raises: Error: If the path cannot be accessed

Args

• path: string: Path to the file or directory

Returns

dict: Dictionary with keys: - size: File size in bytes (int) - modified: Last modification time as seconds since epoch (float) - created: Creation time as seconds since epoch (float or None) - is_dir: Whether it’s a directory (bool) - is_file: Whether it’s a regular file (bool) - is_symlink: Whether it’s a symbolic link (bool) - permissions: Human-readable permissions string (str, e.g., “rw-r–r–”) - mode: Numeric permissions in octal (int)

fs_mkdir()

def fs_mkdir(path, parents, exist_ok) -> NoneType

Create a directory.

Raises: Error: If the directory cannot be created

Args

• path: string: Path to the directory to create
• parents: bool: If True, create parent directories as needed (like mkdir -p)
• exist_ok: bool: If True, don’t error if directory already exists

Returns

None

fs_modified()

def fs_modified(path) -> float

Get the modification time of a file.

Raises: Error: If the file cannot be accessed

Args

• path: string: Path to the file

Returns

float: Modification time as seconds since Unix epoch (January 1, 1970)

fs_move()

def fs_move(src, dst, overwrite) -> NoneType

Move or rename a file or directory.

Creates parent directories for the destination if needed.

Raises: Error: If destination exists and overwrite=False, or if move fails

Args

• src: string: Source path
• dst: string: Destination path
• overwrite: bool: If True, overwrite destination if it exists

Returns

None

fs_read_bytes()

def fs_read_bytes(path) -> list

Read a file as a list of byte values (0-255).

Raises: Error: If the file cannot be read

Args

• path: string: Path to the file

Returns

list: List of integers representing bytes (0-255)

fs_read_directory()

def fs_read_directory(path) -> list

List the contents of a directory.

Returns a list of full paths to entries in the directory. The list is not sorted and includes both files and subdirectories.

Raises: Error: If the directory cannot be read or does not exist

Args

• path: string: Path to the directory

Returns

list: List of full paths to directory entries

fs_read_globs()

def fs_read_globs(includes, excludes, root, include_files, include_dirs, follow_symlinks, max_depth) -> list

Resolve include/exclude glob patterns to matching filesystem paths.

This function walks include roots and returns a deduplicated list of paths matching any include pattern and no exclude patterns.

Raises: Error: If options are invalid or directory walking fails

Args

• includes: list: Required list of glob patterns to include.
• excludes: Optional list of glob patterns to exclude.
• root: string: Base directory used for relative include roots and matching.
• include_files: bool: Include file entries in results (default: True).
• include_dirs: bool: Include directory entries in results (default: False).
• follow_symlinks: bool: Follow symlinks while walking (default: False).
• max_depth: Optional maximum walk depth relative to each include root.

Returns

list: Deduplicated list of matching paths

fs_read_json()

def fs_read_json(path) -> dict

Read and parse a JSON file into a dictionary.

Raises: Error: If the file cannot be read or is not valid JSON

Args

• path: string: Path to the JSON file

Returns

dict: Parsed JSON data as a Starlark dictionary

fs_read_lines()

def fs_read_lines(path) -> list

Read a text file as a list of lines (newlines stripped).

Raises: Error: If the file cannot be read

Args

• path: string: Path to the text file

Returns

list: List of strings, one per line (without newline characters)

fs_read_link()

def fs_read_link(path) -> string

Read the target of a symbolic link.

Raises: Error: If the path is not a symlink or cannot be read

Args

• path: string: Path to the symbolic link

Returns

str: The target path that the symlink points to

fs_read_text()

def fs_read_text(path) -> string

Read the entire contents of a text file.

Raises: Error: If the file cannot be read or does not exist

Args

• path: string: Path to the text file

Returns

str: The complete file contents as a string

fs_read_toml()

def fs_read_toml(path) -> dict

Read and parse a TOML file into a dictionary.

Raises: Error: If the file cannot be read or is not valid TOML

Args

• path: string: Path to the TOML file

Returns

dict: Parsed TOML data as a Starlark dictionary

fs_read_yaml()

def fs_read_yaml(path) -> dict

Read and parse a YAML file into a dictionary.

Raises: Error: If the file cannot be read or is not valid YAML

Args

• path: string: Path to the YAML file

Returns

dict: Parsed YAML data as a Starlark dictionary

fs_remove()

def fs_remove(path, recursive, missing_ok) -> NoneType

Remove a file or directory.

Raises: Error: If path doesn’t exist and missing_ok=False, or if removal fails

Args

• path: string: Path to remove
• recursive: bool: If True, recursively remove directories and contents
• missing_ok: bool: If True, don’t error if path doesn’t exist

Returns

None

fs_set_permissions()

def fs_set_permissions(path, mode) -> NoneType

Set file permissions using numeric mode (Unix octal notation).

Raises: Error: If permissions cannot be set (may not be supported on all OS)

Args

• path: string: Path to the file
• mode: int: Numeric permissions in octal (e.g., 0o644, 0o755, 0o600)

Returns

None

fs_size()

def fs_size(path) -> int

Get the size of a file in bytes.

Raises: Error: If the file cannot be accessed

Args

• path: string: Path to the file

Returns

int: File size in bytes

fs_symlink()

def fs_symlink(target, link) -> NoneType

Create a symbolic link.

Creates a symlink at link that points to target.

Raises: Error: If the symlink cannot be created

Args

• target: string: The target path that the symlink points to
• link: string: The symlink path to create

Returns

None

fs_touch()

def fs_touch(path, create, update_mtime) -> NoneType

Update file modification time or create an empty file.

Raises: Error: If file cannot be created or modified

Args

• path: string: Path to the file
• create: bool: If True, create file if it doesn’t exist
• update_mtime: bool: If True, update modification time to now

Returns

None

fs_walk_directory()

def fs_walk_directory(path, callback, recursive, follow_symlinks, include_files, include_dirs, max_depth) -> list

Walk a directory and invoke a callback for each matching entry.

The callback receives an entry dictionary with: - path: Full entry path - relative_path: Path relative to path - name: Basename of the entry - depth: Walk depth from root directory - is_file: True for files - is_dir: True for directories - is_symlink: True for symbolic links

If the callback returns None, that entry is skipped in the returned list. Any other callback return value is collected in the output list.

Raises: Error: If options are invalid, walking fails, or callback raises

Args

• path: string: Root directory to walk.
• callback: Function called as callback(entry_dict) -> any.
• recursive: bool: Recurse into subdirectories (default: True).
• follow_symlinks: bool: Follow symlinks while walking (default: False).
• include_files: bool: Include file entries (default: True).
• include_dirs: bool: Include directory entries (default: False).
• max_depth: Optional maximum walk depth (ignored when recursive=False).

Returns

list: List of non-None values returned by the callback

fs_with_file_lock()

def fs_with_file_lock(lock_path, callback, exclusive, blocking, create)

Acquire an advisory file lock for the duration of a callback.

The callback is executed while the lock is held, and the callback’s return value is returned by this function.

Raises: Error: If lock acquisition fails or callback raises

Args

• lock_path: string: Path to the lock file to use
• callback: Zero-argument function/lambda to run while locked
• exclusive: bool: If True, acquire an exclusive (writer) lock; otherwise shared
• blocking: bool: If True, wait until lock can be acquired; otherwise error if busy
• create: bool: If True, create the lock file (and parent directories) when needed

Returns

Any: The return value from callback

fs_write_bytes()

def fs_write_bytes(path, data) -> NoneType

Write a list of byte values to a file.

Raises: Error: If bytes are out of range or file cannot be written

Args

• path: string: Path to the file
• data: list: List of integers (0-255) representing bytes

Returns

None

fs_write_json()

def fs_write_json(path, data, pretty) -> NoneType

Write a dictionary to a JSON file.

Raises: Error: If the data cannot be serialized or file cannot be written

Args

• path: string: Path to the JSON file
• data: dict: Dictionary or list to serialize
• pretty: bool: If True (default), write formatted JSON with indentation

Returns

None

fs_write_lines()

def fs_write_lines(path, lines) -> NoneType

Write a list of strings as lines to a file.

Lines are joined with newline characters. Each string in the list becomes one line in the output file.

Raises: Error: If the file cannot be written

Args

• path: string: Path to the file
• lines: list: List of strings to write

Returns

None

fs_write_string_atomic()

def fs_write_string_atomic(path, content, mode) -> NoneType

Atomically write text to a file with proper permissions.

This function writes to a temporary file first, then atomically renames it to the destination. This ensures the file is never left in a partial or corrupt state. Useful for configuration files or critical data.

Raises: Error: If the file cannot be written or permissions cannot be set

Args

• path: string: Path to the file
• content: string: Text content to write
• mode: int: Unix file permissions as octal number (default: 0o644)

Returns

None

fs_write_text()

def fs_write_text(path, content) -> NoneType

Write text content to a file, overwriting if it exists.

Creates parent directories if they don’t exist. If the file already exists, its contents will be completely replaced.

Raises: Error: If the file cannot be created or written

Args

• path: string: Path to the file
• content: string: Text content to write

Returns

None

fs_write_toml()

def fs_write_toml(path, data) -> NoneType

Write a dictionary to a TOML file.

Raises: Error: If the data cannot be serialized or file cannot be written

Args

• path: string: Path to the TOML file
• data: dict: Dictionary to serialize as TOML

Returns

None

fs_write_yaml()

def fs_write_yaml(path, data) -> NoneType

Write a dictionary to a YAML file.

Raises: Error: If the data cannot be serialized or file cannot be written

Args

• path: string: Path to the YAML file
• data: dict: Dictionary or list to serialize as YAML

Returns

None