OutputStream

The output stream for bxl to print values to the console as their result

OutputStream.ensure

def OutputStream.ensure(
artifact: artifact,
) -> bxl.EnsuredArtifact

Marks the artifact as an artifact that should be available to the users at the end of the bxl invocation. Any artifacts that do not get registered via this call is not accessible by users at the end of bxl script.

This function returns an ensured_artifact type that can be printed via ctx.output.print() to print its actual path on disk.

Sample usage:

def _impl_ensure(ctx):
    actions = ctx.bxl_actions().actions
    output = actions.write("my_output", "my_content")
    ensured = ctx.output.ensure(output)
    ctx.output.print(ensured)

---

OutputStream.ensure_multiple

def OutputStream.ensure_multiple(
artifacts: CellPath | None | artifact | bxl.BuildResult | bxl_built_artifacts_iterable | cell_root | cmd_args | label | output_artifact | project_root | resolved_macro | str | tagged_command_line | target_label | transitive_set_args_projection | write_json_cli_args | list[artifact] | dict[typing.Any, bxl.BuildResult] | RunInfo,
)

Same as ensure, but for multiple artifacts. Will preserve the shape of the inputs (i.e. if the resulting Dict of a ctx.build() is passed in, the output will be a Dict where the key is preserved, and the values are converted to ensured_artifacts).

Note that is slower to loop through objects and ensure them one by one than it is to call ensure_multiple() on all the objects at once (if possible). So, it is suggested to use this method when you are only ensuring a few individual artifacts that are not stored in an iterable.

Sample usage:

def _impl_ensure_multiple(ctx):
    outputs = {}
    for target, value in ctx.build(ctx.cli_args.target).items():
    outputs.update({target.raw_target(): ctx.output.ensure_multiple(value.artifacts())})
    ctx.output.print_json(outputs)

---

OutputStream.print

def OutputStream.print(
*args,
sep: str = " ",
) -> None

Outputs results to the console via stdout. These outputs are considered to be the results of a bxl script, which will be displayed to stdout by buck2 even when the script is cached. Accepts an optional separator that defaults to " ".

Prints that are not result of the bxl should be printed via stderr via the stdlib print and pprint. Note that ctx.output.print() is intended for simple outputs. For more complex outputs, the recommendation would be to write them to a file.

Sample usage:

def _impl_print(ctx):
    ctx.output.print("test")

---

OutputStream.print_json

def OutputStream.print_json(
value,
*,
pretty: bool = True,
) -> None

Outputs results to the console via stdout as pretty-printed json. Pretty printing can be turned off by the pretty keyword-only parameter. These outputs are considered to be the results of a bxl script, which will be displayed to stdout by buck2 even when the script is cached.

Prints that are not result of the bxl should be printed via stderr via the stdlib print and pprint.

Sample usage:

def _impl_print_json(ctx):
    outputs = {}
    outputs.update({"foo": bar})
    ctx.output.print_json("test")