* (rules) APIs for creating custom rules based on the core py_binary, py_test,

and py_library rules

([#1647](https://github.com/bazelbuild/rules_python/issues/1647))

"//python/api:executables_bzl",

"//python/api:libraries_bzl",

:::{important}

**Public, but volatile, API.** Some parts are stable, while others are

implementation details and may change more frequently.

:::

:::{important}

**This is public, but volatile, functionality.**

Extending and customizing the rules is supported functionality, but with weaker

backwards compatibility guarantees, and is not fully subject to the normal

backwards compatibility procedures and policies. It's simply not feasible to

support every possible customization with strong backwards compatibility

guarantees.

:::

Because of the rich ecosystem of tools and variety of use cases, APIs are

provided to make it easy to create custom rules using the existing rules as a

basis. This allows implementing behaviors that aren't possible using

wrapper macros around the core rules, and can make certain types of changes

much easier and transparent to implement.

:::{note}

It is not required to extend a core rule. The minimum requirement for a custom

rule is to return the appropriate provider (e.g. {bzl:obj}`PyInfo` etc).

Extending the core rules is most useful when you want all or most of the

behavior of a core rule.

:::

Follow or comment on https://github.com/bazelbuild/rules_python/issues/1647

for the development of APIs to support custom derived rules.

Custom rules can be created using the core rules as a basis by using their rule

builder APIs.

* [`//python/apis:executables.bzl`](#python-apis-executables-bzl): builders for

executables.

* [`//python/apis:libraries.bzl`](#python-apis-libraries-bzl): builders for

libraries.

These builders create {bzl:obj}`ruleb.Rule` objects, which are thin

wrappers around the keyword arguments eventually passed to the `rule()`

function. These builder APIs give access to the _entire_ rule definition and

allow arbitrary modifications.

This is level of control is powerful, but also volatile. A rule definition

contains many details that _must_ change as the implementation changes. What

is more or less likely to change isn't known in advance, but some general

rules are:

* Additive behavior to public attributes will be less prone to breaking.

* Internal attributes that directly support a public attribute are likely

reliable.

* Internal attributes that support an action are more likely to change.

* Rule toolchains are moderately stable (toolchains are mostly internal to

how a rule works, but custom toolchains are supported).

In this example, we derive from `py_library` a custom rule that verifies source

code contains the word "snakes". It does this by:

* Adding an implicit dependency on a checker program

* Calling the base implementation function

* Running the checker on the srcs files

* Adding the result to the `_validation` output group (a special output

group for validation behaviors).

To users, they can use `has_snakes_library` the same as `py_library`. The same

is true for other targets that might consume the rule.

In this example, we derive from `py_binary` to force building for a particular

platform. We do this by:

* Adding an additional output to the rule's cfg

* Calling the base transition function

* Returning the new transition outputs

load("@rules_python//python/api:executables.bzl", "executables")

def _force_linux_impl(settings, attr, base_impl):

settings = base_impl(settings, attr)

settings["//command_line_option:platforms"] = ["//my/platforms:linux"]

return settings

def create_rule():

r = executables.py_binary_rule_builder()

base_impl = r.cfg.implementation()

r.cfg.set_implementation(

lambda settings, attr: _force_linux_impl(settings, attr, base_impl)

)

r.cfg.add_output("//command_line_option:platforms")

return r.build()

py_linux_binary = create_linux_binary_rule()

Users can then use `py_linux_binary` the same as a regular py_binary. It will

act as if `--platforms=//my/platforms:linux` was specified when building it.

bzl_library(

name = "executables_bzl",

srcs = ["executables.bzl"],

visibility = ["//visibility:public"],

deps = [

"//python/private:py_binary_rule_bzl",

"//python/private:py_executable_bzl",

"//python/private:py_test_rule_bzl",

],

)

bzl_library(

name = "libraries_bzl",

srcs = ["libraries.bzl"],

visibility = ["//visibility:public"],

deps = [

"//python/private:py_library_bzl",

],

)

load("//python/private:py_binary_rule.bzl", "create_py_binary_rule_builder")

load("//python/private:py_executable.bzl", "create_executable_rule_builder")

load("//python/private:py_test_rule.bzl", "create_py_test_rule_builder")

executables = struct(

py_binary_rule_builder = create_py_binary_rule_builder,

py_test_rule_builder = create_py_test_rule_builder,

executable_rule_builder = create_executable_rule_builder,

)

load("//python/private:py_library.bzl", "create_py_library_rule_builder")

libraries = struct(

py_library_rule_builder = create_py_library_rule_builder,

)

":precompile_bzl",

def create_py_binary_rule_builder():

"""Create a rule builder for a py_binary.

py_binary = create_py_binary_rule_builder().build()

"""Create a rule builder for an executable Python program.