File system - Aspect Build

function FileSystem.copy

def FileSystem.copy(
from: str,
to: str,
/
) -> int

Copies the contents of one file to another. This function will also copy the permission bits of the original file to the destination file. This function will overwrite the contents of to. Note that if from and to both point to the same file, then the file will likely get truncated by this operation. On success, the total number of bytes copied is returned and it is equal to the length of the to file as reported by metadata. This function will return an error in the following situations, but is not limited to just these cases:

from is neither a regular file nor a symlink to a regular file.
from does not exist.
The current process does not have the permission rights to read from or write to.
The parent directory of to doesn’t exist.

function FileSystem.create

def FileSystem.create(
path: str,
/
) -> std.io.Writable

Creates (or truncates) a file for writing and returns it as a writable stream. Mirrors std::fs::File::create — the file is opened write-only and truncated to zero length, or created if it does not exist. function FileSystem.create_dir

def FileSystem.create_dir(
path: str,
/
) -> None

Creates a new, empty directory at the provided path. This function will return an error in the following situations, but is not limited to just these cases:

User lacks permissions to create directory at path.
A parent of the given path doesn’t exist. (To create a directory and all its missing parents at the same time, use the createidirlall function.)
path already exists.

NOTE: If a parent of the given path doesn’t exist, this function will return an error. To create a directory and all its missing parents at the same time, use the createidirlall function. function FileSystem.create_dir_all

def FileSystem.create_dir_all(
path: str,
/
) -> None

Recursively create a directory and all of its parent components if they are missing. This function is not atomic. If it returns an error, any parent components it was able to create will remain. If the empty path is passed to this function, it always succeeds without creating any directories. The function will return an error if any directory specified in path does not exist and could not be created. There may be other error conditions; see create_dir for specifics. function FileSystem.exists

def FileSystem.exists(
path: str,
/
) -> bool

Returns true if the path points at an existing entity. This function will traverse symbolic links to query information about the destination file. In case of broken symbolic links this will return false. Note that while this avoids some pitfalls of the exists() method, it still can not prevent time-of-check to time-of-use (TOCTOU) bugs. You should only use it in scenarios where those bugs are not an issue. function FileSystem.hard_link

def FileSystem.hard_link(
original: str,
link: str,
/
) -> None

Creates a new hard link on the filesystem. The link path will be a link pointing to the original path. Note that systems often require these two paths to both be located on the same filesystem. If original names a symbolic link, it is platform-specific whether the symbolic link is followed. On platforms where it’s possible to not follow it, it is not followed, and the created hard link points to the symbolic link itself. This function will return an error in the following situations, but is not limited to just these cases:

The original path is not a file or doesn’t exist.
The ‘link’ path already exists.

function FileSystem.is_dir

def FileSystem.is_dir(
path: str,
/
) -> bool

Returns true if this path is for a directory. This function will return an error in the following situations, but is not limited to just these cases:

The user lacks permissions to perform metadata call on path.
path does not exist.

function FileSystem.is_file

def FileSystem.is_file(
path: str,
/
) -> bool

Returns true if this path is for a regular file. This function will return an error in the following situations, but is not limited to just these cases:

The user lacks permissions to perform metadata call on path.
path does not exist.

function FileSystem.metadata

def FileSystem.metadata(
path: str,
/
) -> fs.Metadata

Returns the metadata about the given file or directory. This function will return an error in the following situations, but is not limited to just these cases:

The user lacks permissions to perform metadata call on path.
path does not exist.

The modified, accessed, created fields of the Metadata result might not be available on all platforms, and will be set to None on platforms where they is not available. The executable field reflects the Unix execute bit; it is always false on non-Unix platforms. function FileSystem.mkdtemp

def FileSystem.mkdtemp(
*,
prefix: str = "",
parent: str = ""
) -> str

Creates a new temporary directory with a unique name and returns its path. The directory is created inside parent (defaults to the system temp dir). The caller is responsible for removing it when done. function FileSystem.open

def FileSystem.open(
path: str,
/
) -> std.io.Readable

Opens a file for reading and returns it as a readable stream. The returned stream can be passed directly as the data argument to ctx.http().post() or ctx.http().put() for streaming uploads, or iterated over / read directly. function FileSystem.read_dir

def FileSystem.read_dir(
path: str,
/
) -> list[fs.DirEntry]

Returns an iterator over the entries within a directory. This function will return an error in the following situations, but is not limited to just these cases:

The provided path doesn’t exist.
The process lacks permissions to view the contents.
The path points at a non-directory file.

function FileSystem.read_link

def FileSystem.read_link(
path: str,
/
) -> str

Reads a symbolic link, returning the file that the link points to. This function will return an error in the following situations, but is not limited to just these cases:

path is not a symbolic link.
path does not exist.

function FileSystem.read_to_string

def FileSystem.read_to_string(
path: str,
/
) -> str

Reads the entire contents of a file into a string. This function will return an error under a number of different circumstances. Some of these error conditions are:

The specified file does not exist.
The user lacks permission to get the specified access rights for the file.
The user lacks permission to open one of the directory components of the specified path.

function FileSystem.remove_dir

def FileSystem.remove_dir(
path: str,
/
) -> None

Removes an empty directory. If you want to remove a directory that is not empty, as well as all of its contents recursively, consider using remove_dir_all instead. This function will return an error in the following situations, but is not limited to just these cases:

path doesn’t exist.
path isn’t a directory.
The user lacks permissions to remove the directory at the provided path.
The directory isn’t empty.

function FileSystem.remove_dir_all

def FileSystem.remove_dir_all(
path: str,
/
) -> None

Removes a directory at this path, after removing all its contents. Use carefully! This function does not follow symbolic links and it will simply remove the symbolic link itself. See remove_file and remove_dir for possible errors. function FileSystem.remove_file

def FileSystem.remove_file(
path: str,
/
) -> None

Removes a file from the filesystem. Note that there is no guarantee that the file is immediately deleted (e.g., depending on platform, other open file descriptors may prevent immediate removal). This function will return an error in the following situations, but is not limited to just these cases:

path points to a directory.
The file doesn’t exist.
The user lacks permissions to remove the file.

function FileSystem.rename

def FileSystem.rename(
from: str,
to: str,
/
) -> None

Renames a file or directory to a new name, replacing the original file if to already exists. This will not work if the new name is on a different mount point. This function will return an error in the following situations, but is not limited to just these cases:

from does not exist.
The user lacks permissions to view contents.
from and to are on separate filesystems.

function FileSystem.symlink_metadata

def FileSystem.symlink_metadata(
path: str,
/
) -> fs.Metadata

Queries the metadata about a file without following symlinks. This function will return an error in the following situations, but is not limited to just these cases:

The user lacks permissions to perform metadata call on path.
path does not exist.

def FileSystem.try_append(
path: str,
content: str,
/
) -> bool

Appends a string to the end of a file, creating it if it does not exist. Opens the file with OpenOptions::append(true) so concurrent writers see their bytes interleaved at record boundaries rather than racing. POSIX O_APPEND is atomic for writes ≤ PIPE_BUF, which covers the short single-line records this is designed for (the runner_job_history lines fit comfortably). The parent directory must exist; this function will not create intermediate directories. Returns True on success and False on any I/O error (parent directory missing, permissions denied, target is a directory, etc.). Errors are swallowed because the primary caller is the runner job history hook, where a write failure must never fail the task. function FileSystem.try_read_to_string

def FileSystem.try_read_to_string(
path: str,
/
) -> str

Reads the entire contents of a file into a string, or returns "" on any I/O error (missing file, permission denied, non-UTF-8 content, transient read failure). Companion to try_append: the silent fall-through lets callers handle never-fail invariants without try/except — e.g. the runner job history dedup read, where a failed read must degrade to “assume empty file” rather than fail the task. function FileSystem.write

def FileSystem.write(
path: str,
content: str,
/
) -> None

Writes a string as the entire contents of a file. This function will create a file if it does not exist, and will entirely replace its contents if it does. Depending on the platform, this function may fail if the full directory path does not exist. This is a convenience function for using fs.create and [write_all] with fewer imports.