Skip to main content

attrs type

This type is available as a global attrs symbol, to allow the definition of attributes to the rule function.

As an example:

rule(impl = _impl, attrs = {"foo": attrs.string(), "bar": attrs.int(default = 42)})

Most attributes take at least two optional parameters:

  • A doc parameter, which specifies documentation for the attribute.

  • A default parameter, which if present specifies the default value for the attribute if omitted. If there is no default, the user of the rule must supply that parameter.

Each attribute defines what values it accepts from the user, and which values it gives to the rule. For simple types like attrs.string these are the same, for more complex types like attrs.dep these are different (string from the user, dependency to the rule).

attrs.any​

def attrs.any(*, doc: str = "", default = _) -> attribute

Takes most builtin literals and passes them to the rule as a string. Discouraged, as it provides little type safety and destroys the structure.

attrs.arg​

def attrs.arg(
    *,
    json: bool = False,
    default = _,
    doc: str = "",
    anon_target_compatible: bool = False
) -> attribute

Takes a command line argument from the user and supplies a cmd_args compatible value to the rule. The argument may contain special macros such as $(location :my_target) or $(exe :my_target) which will be replaced with references to those values in the rule. Takes in an optional anon_target_compatible flag, which indicates whether the args can be passed into anon targets. Note that there is a slight memory hit when using this flag.

attrs.bool​

def attrs.bool(*, default = _, doc: str = "") -> attribute

Takes a boolean and passes it to the rule as a boolean.

attrs.configuration_label​

def attrs.configuration_label(*, doc: str = "") -> attribute

attrs.configured_dep​

def attrs.configured_dep(
    *,
    providers: list[typing.Any] | tuple = [],
    default = _,
    doc: str = ""
) -> attribute

attrs.default_only​

def attrs.default_only(
    inner: attribute,
    /,
    *,
    doc: str = ""
) -> attribute

Rejects all values and uses the default for the inner argument. Often used to resolve dependencies, which otherwise can't be resolved inside a rule.

attrs.default_only(attrs.dep(default = "foo//my_package:my_target"))

attrs.dep​

def attrs.dep(
    *,
    providers: list[typing.Any] | tuple = [],
    pulls_plugins: list[typing.Any] | tuple = [],
    pulls_and_pushes_plugins: all_plugins | list[typing.Any] | tuple = _,
    default = _,
    doc: str = ""
) -> attribute

Takes a target from the user, as a string, and supplies a dependency to the rule. A target can be specified as an absolute dependency foo//bar:baz, omitting the cell (//bar:baz) or omitting the package name (:baz).

If supplied the providers argument ensures that specific providers will be present on the dependency.

attrs.dict​

def attrs.dict(
    key: attribute,
    value: attribute,
    *,
    sorted: bool = False,
    default = _,
    doc: str = ""
) -> attribute

Takes a dict from the user, supplies a dict to the rule.

attrs.enum​

def attrs.enum(
    variants: list[str] | tuple[str, ...],
    /,
    *,
    default = _,
    doc: str = ""
) -> attribute

Takes a string from one of the variants given, and gives that string to the rule. Strings are matched case-insensitively, and always passed to the rule lowercase.

attrs.exec_dep​

def attrs.exec_dep(
    *,
    providers: list[typing.Any] | tuple = [],
    default = _,
    doc: str = ""
) -> attribute

Takes a target from the user, as a string, and supplies a dependency to the rule. The dependency will transition to the execution platform. Use exec_dep if you plan to execute things from this dependency as part of the compilation.

attrs.int​

def attrs.int(*, default = _, doc: str = "") -> attribute

Takes an int from the user, supplies an int to the rule.

attrs.label​

def attrs.label(*, default = _, doc: str = "") -> attribute

Takes a target (as per deps) and passes a label to the rule. Validates that the target exists, but does not introduce a dependency on it.

attrs.list​

def attrs.list(
    inner: attribute,
    /,
    *,
    default = _,
    doc: str = ""
) -> attribute

Takes a list from the user, supplies a list to the rule.

attrs.named_set​

def attrs.named_set(
    value_type: attribute,
    /,
    *,
    sorted: bool = False,
    default = _,
    doc: str = ""
) -> attribute

attrs.one_of​

def attrs.one_of(*args: attribute, default = _, doc: str = "") -> attribute

Given a list of alternative attributes, selects the first that matches and gives that to the rule.

attrs.option​

def attrs.option(
    inner: attribute,
    /,
    *,
    default = _,
    doc: str = ""
) -> attribute

Takes a value that may be None or some inner type, and passes either None or the value corresponding to the inner to the rule. Often used to make a rule optional:

attrs.option(attr.string(), default = None)

attrs.plugin_dep​

def attrs.plugin_dep(
    *,
    kind,
    default = _,
    doc: str = ""
) -> attribute

attrs.query​

def attrs.query(*, doc: str = "") -> attribute

attrs.regex​

def attrs.regex(*, default = _, doc: str = "") -> attribute

Currently an alias for attrs.string.

attrs.set​

def attrs.set(
    value_type: attribute,
    /,
    *,
    sorted: bool = False,
    default = _,
    doc: str = ""
) -> attribute

attrs.source​

def attrs.source(
    *,
    allow_directory: bool = False,
    default = _,
    doc: str = ""
) -> attribute

Takes a source file from the user, supplies an artifact to the rule. The source file may be specified as a literal string (representing the path within this package), or a target (which must have a DefaultInfo with a default_outputs value).

attrs.split_transition_dep​

def attrs.split_transition_dep(
    *,
    providers: list[typing.Any] | tuple = [],
    cfg,
    default = _,
    doc: str = ""
) -> attribute

attrs.string​

def attrs.string(
    *,
    default = _,
    validate = _,
    doc: str = ""
) -> attribute

Takes a string from the user, supplies a string to the rule.

attrs.toolchain_dep​

def attrs.toolchain_dep(
    *,
    providers: list[typing.Any] | tuple = [],
    default = _,
    doc: str = ""
) -> attribute

Takes a target from the user, as a string, and supplies a dependency to the rule. The dependency will be a toolchain dependency, meaning that its execution platform dependencies will be used to select the execution platform for this rule.

attrs.transition_dep​

def attrs.transition_dep(
    *,
    providers: list[typing.Any] | tuple = [],
    cfg,
    default = _,
    doc: str = ""
) -> attribute

attrs.tuple​

def attrs.tuple(*args: attribute, default = _, doc: str = "") -> attribute

Takes a tuple of values and gives a tuple to the rule.

attrs.versioned​

def attrs.versioned(value_type: attribute, *, doc: str = "") -> attribute