Skip to main content

Filesystem

Provides some basic tracked filesystem access for bxl functions so that they can meaningfully detect simple properties of artifacts, and source directories.

Filesystem.abs_path_unsafe

def Filesystem.abs_path_unsafe(
expr: artifact | bxl.FileNode | str,
) -> str

Returns the absolute path, given the file expression. Use at your own risk, as the current working directory may have been changed when this function is called. In addition, passing the absolute path into actions that are run remotely will most likely result in failures since the absolute path most likely differs locally vs remotely.

Sample usage:

def _impl_abs_path_unsafe(ctx):
    ctx.output.print(ctx.fs.abs_path_unsafe("bin"))

Filesystem.exists

def Filesystem.exists(
expr: artifact | bxl.FileNode | str,
) -> bool

Check if a path exists on disk, taking advantage of Buck's cached filesystem. Takes in a literal, a source artifact (via artifact), or a file_node.

Sample usage:

def _impl_exists(ctx):
    ctx.output.print(ctx.fs.exists("bin"))

Filesystem.is_dir

def Filesystem.is_dir(
expr: artifact | bxl.FileNode | str,
) -> bool

Returns whether the provided path is a dir. Returns false is the dir does not exist. The input is a either a literal, a source artifact (via artifact), or a file_node.

Sample usage:

def _impl_is_dir(ctx):
    ctx.output.print(ctx.fs.is_dir("bin"))

Filesystem.is_file

def Filesystem.is_file(
expr: artifact | bxl.FileNode | str,
) -> bool

Returns whether the provided path is a file. Returns false is the file does not exist. The input is a either a literal, a source artifact (via artifact), or a file_node.

Sample usage:

def _impl_is_file(ctx):
    ctx.output.print(ctx.fs.is_dir("bin"))

Filesystem.list

def Filesystem.list(
expr: artifact | bxl.FileNode | str,
*,
dirs_only: bool = False,
) -> read_dir_set

Returns all the contents of the given input that points to a directory. Errors if the given path is a file. Takes an optional boolean dirs_only to only return directories, defaults to false.

The input is a either a literal, a source artifact (via artifact), or a file_node.

Sample usage:

def _impl_list(ctx):
    list_results = ctx.fs.list("bin")
    for result in list_results:
        ctx.output.print(result)

Filesystem.project_rel_path

def Filesystem.project_rel_path(
expr: artifact | bxl.FileNode | str,
) -> str

Returns the relative path to the project root, given the file expression.

Sample usage:

def project_rel_path(ctx):
    ctx.output.print(ctx.fs.project_rel_path("bin"))

Filesystem.source

def Filesystem.source(
expr: artifact | bxl.FileNode | str,
target_hint: None | bxl.UnconfiguredTargetNode | str | target_label | target_set | list[bxl.UnconfiguredTargetNode | str | target_label] = None,
) -> artifact

Returns the source artifact for a path and an optional target hint (unconfigured target label or node) which points to the owning package. If no target hint is given, the nearest package will be used to guess the desired artifact. The path should be either an absolute path, or a project relative path.