Skip to main content

fs type

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

fs.abs_path_unsafe​

def fs.abs_path_unsafe(expr: artifact | file_node | 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"))

fs.exists​

def fs.exists(expr: artifact | file_node | 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"))

fs.is_dir​

def fs.is_dir(expr: artifact | file_node | 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"))

fs.is_file​

def fs.is_file(expr: artifact | file_node | 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"))

fs.list​

def fs.list(
    expr: artifact | file_node | 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)

fs.project_rel_path​

def fs.project_rel_path(expr: artifact | file_node | 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"))

fs.source​

def fs.source(
    expr: artifact | file_node | str,
    target_hint: None | str | target_label | target_set | unconfigured_target_node | list[str | target_label | unconfigured_target_node] = 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.