Custom init callback for providers

Implements #14392

RELNOTES: provider() has a new parameter: init, a callback for performing
pre-processing and validation of field values. Iff this parameter is set,
provider() returns a tuple of 2 elements: the usual provider symbol (which,
when called, invokes init) and a raw constructor (which bypasses init).
PiperOrigin-RevId: 422702617

Author: tetromino

site/docs/skylark/rules.md

@@ -570,6 +570,89 @@ def _example_library_impl(ctx):
   ]
 ```
 
+##### Custom initialization of providers
+
+It's possible to guard the instantiation of a provider with custom
+preprocessing and validation logic. This can be used to ensure that all
+provider instances obey certain invariants, or to give users a cleaner API for
+obtaining an instance.
+
+This is done by passing an `init` callback to the
+[`provider`](lib/globals.html#provider) function. If this callback is given, the
+return type of `provider()` changes to be a tuple of two values: the provider
+symbol that is the ordinary return value when `init` is not used, and a "raw
+constructor".
+
+In this case, when the provider symbol is called, instead of directly returning
+a new instance, it will forward the arguments along to the `init` callback. The
+callback's return value must be a dict mapping field names (strings) to values;
+this is used to initialize the fields of the new instance. Note that the
+callback may have any signature, and if the arguments do not match the signature
+an error is reported as if the callback were invoked directly.
+
+The raw constructor, by contrast, will bypass the `init` callback.
+
+The following example uses `init` to preprocess and validate its arguments:
+
+```python
+# //pkg:exampleinfo.bzl
+
+_core_headers = [...]  # private constant representing standard library files
+
+# It's possible to define an init accepting positional arguments, but
+# keyword-only arguments are preferred.
+def _exampleinfo_init(*, files_to_link, headers = None, allow_empty_files_to_link = False):
+    if not files_to_link and not allow_empty_files_to_link:
+        fail("files_to_link may not be empty")
+    all_headers = depset(_core_headers, transitive = headers)
+    return {'files_to_link': files_to_link, 'headers': all_headers}
+
+ExampleInfo, _new_exampleinfo = provider(
+    ...
+    init = _exampleinfo_init)
+
+export ExampleInfo
+```
+
+A rule implementation may then instantiate the provider as follows:
+
+```python
+    ExampleInfo(
+        files_to_link=my_files_to_link,  # may not be empty
+        headers = my_headers,  # will automatically include the core headers
+    )
+```
+
+The raw constructor can be used to define alternative public factory functions
+that do not go through the `init` logic. For example, in exampleinfo.bzl we
+could define:
+
+```python
+def make_barebones_exampleinfo(headers):
+    """Returns an ExampleInfo with no files_to_link and only the specified headers."""
+    return _new_exampleinfo(files_to_link = depset(), headers = all_headers)
+```
+
+Typically, the raw constructor is bound to a variable whose name begins with an
+underscore (`_new_exampleinfo` above), so that user code cannot load it and
+generate arbitrary provider instances.
+
+Another use for `init` is to simply prevent the user from calling the provider
+symbol altogether, and force them to use a factory function instead:
+
+```python
+def _exampleinfo_init_banned(*args, **kwargs):
+    fail("Do not call ExampleInfo(). Use make_exampleinfo() instead.")
+
+ExampleInfo, _new_exampleinfo = provider(
+    ...
+    init = _exampleinfo_init_banned)
+
+def make_exampleinfo(...):
+    ...
+    return _new_exampleinfo(...)
+```
+
 <a name="executable-rules"></a>
 
 ## Executable rules and test rules

src/main/java/com/google/devtools/build/lib/analysis/starlark/StarlarkRuleClassFunctions.java

@@ -77,7 +77,6 @@
 import com.google.devtools.build.lib.packages.Package.NameConflictException;
 import com.google.devtools.build.lib.packages.PackageFactory.PackageContext;
 import com.google.devtools.build.lib.packages.PredicateWithMessage;
-import com.google.devtools.build.lib.packages.Provider;
 import com.google.devtools.build.lib.packages.RuleClass;
 import com.google.devtools.build.lib.packages.RuleClass.Builder.RuleClassType;
 import com.google.devtools.build.lib.packages.RuleClass.ToolchainTransitionMode;
@@ -272,14 +271,25 @@ public static RuleClass getTestBaseRule(RuleDefinitionEnvironment env) {
   }
 
   @Override
-  public Provider provider(String doc, Object fields, StarlarkThread thread) throws EvalException {
+  public Object provider(String doc, Object fields, Object init, StarlarkThread thread)
+      throws EvalException {
     StarlarkProvider.Builder builder = StarlarkProvider.builder(thread.getCallerLocation());
     if (fields instanceof Sequence) {
       builder.setSchema(Sequence.cast(fields, String.class, "fields"));
     } else if (fields instanceof Dict) {
       builder.setSchema(Dict.cast(fields, String.class, String.class, "fields").keySet());
     }
-    return builder.build();
+    if (init == Starlark.NONE) {
+      return builder.build();
+    } else {
+      if (init instanceof StarlarkCallable) {
+        builder.setInit((StarlarkCallable) init);
+      } else {
+        throw Starlark.errorf("got %s for init, want callable value", Starlark.type(init));
+      }
+      StarlarkProvider provider = builder.build();
+      return Tuple.of(provider, provider.createRawConstructor());
+    }
   }
 
   // TODO(bazel-team): implement attribute copy and other rule properties

src/main/java/com/google/devtools/build/lib/packages/StarlarkInfo.java

@@ -126,9 +126,9 @@ static StarlarkInfo createFromNamedArgs(
       List<String> unexpected = unexpectedKeys(schema, table, n);
       if (unexpected != null) {
         throw Starlark.errorf(
-            "unexpected keyword%s %s in call to instantiate provider %s",
+            "got unexpected field%s '%s' in call to instantiate provider %s",
             unexpected.size() > 1 ? "s" : "",
-            Joiner.on(", ").join(unexpected),
+            Joiner.on("', '").join(unexpected),
             provider.getPrintableName());
       }
     }

src/main/java/com/google/devtools/build/lib/packages/StarlarkProvider.java

@@ -14,14 +14,17 @@
 
 package com.google.devtools.build.lib.packages;
 
+import com.google.common.annotations.VisibleForTesting;
 import com.google.common.base.Preconditions;
 import com.google.common.collect.ImmutableList;
 import com.google.devtools.build.lib.cmdline.Label;
 import com.google.devtools.build.lib.events.EventHandler;
 import com.google.devtools.build.lib.util.Fingerprint;
 import java.util.Collection;
+import java.util.Map;
 import java.util.Objects;
 import javax.annotation.Nullable;
+import net.starlark.java.eval.Dict;
 import net.starlark.java.eval.EvalException;
 import net.starlark.java.eval.Printer;
 import net.starlark.java.eval.Starlark;
@@ -39,6 +42,11 @@
  * providers can have any set of fields on them, whereas instances of schemaful providers may have
  * only the fields that are named in the schema.
  *
+ * <p>{@code StarlarkProvider} may have a custom initializer callback, which might perform
+ * preprocessing or validation of field values. This callback (if defined) is automatically invoked
+ * when the provider is called. To create instances of the provider without calling the initializer
+ * callback, use the callable returned by {@code StarlarkProvider#createRawConstructor}.
+ *
  * <p>Exporting a {@code StarlarkProvider} creates a key that is used to uniquely identify it.
  * Usually a provider is exported by calling {@link #export}, but a test may wish to just create a
  * pre-exported provider directly. Exported providers use only their key for {@link #equals} and
@@ -53,6 +61,11 @@ public final class StarlarkProvider implements StarlarkCallable, StarlarkExporta
   // as it lets us verify table ⊆ schema in O(n) time without temporaries.
   @Nullable private final ImmutableList<String> schema;
 
+  // Optional custom initializer callback. If present, it is invoked with the same positional and
+  // keyword arguments as were passed to the provider constructor. The return value must be a
+  // Starlark dict mapping field names (string keys) to their values.
+  @Nullable private final StarlarkCallable init;
+
   /** Null iff this provider has not yet been exported. Mutated by {@link export}. */
   @Nullable private Key key;
 
@@ -78,6 +91,8 @@ public static final class Builder {
 
     @Nullable private ImmutableList<String> schema;
 
+    @Nullable private StarlarkCallable init;
+
     @Nullable private Key key;
 
     private Builder(Location location) {
@@ -93,6 +108,24 @@ public Builder setSchema(Collection<String> schema) {
       return this;
     }
 
+    /**
+     * Sets the custom initializer callback for instances of the provider built by this builder.
+     *
+     * <p>The initializer callback will be automatically invoked when the provider is called. To
+     * bypass the custom initializer callback, use the callable returned by {@link
+     * StarlarkProvider#createRawConstructor}.
+     *
+     * @param init A callback that accepts the arguments passed to the provider constructor, and
+     *     which returns a dict mapping field names to their values. The resulting provider instance
+     *     is created as though the dict were passed as **kwargs to the raw constructor. In
+     *     particular, for a schemaful provider, the dict may not contain keys not listed in the
+     *     schema.
+     */
+    public Builder setInit(StarlarkCallable init) {
+      this.init = init;
+      return this;
+    }
+
     /** Sets the provider built by this builder to be exported with the given key. */
     public Builder setExported(Key key) {
       this.key = key;
@@ -101,32 +134,102 @@ public Builder setExported(Key key) {
 
     /** Builds a StarlarkProvider. */
     public StarlarkProvider build() {
-      return new StarlarkProvider(location, schema, key);
+      return new StarlarkProvider(location, schema, init, key);
     }
   }
 
   /**
    * Constructs the provider.
    *
-   * <p>If {@code key} is null, the provider is unexported. If {@code schema} is null, the provider
-   * is schemaless.
+   * <p>If {@code schema} is null, the provider is schemaless. If {@code init} is null, no custom
+   * initializer callback will be used (i.e., calling the provider is the same as simply calling the
+   * raw constructor). If {@code key} is null, the provider is unexported.
    */
   private StarlarkProvider(
-      Location location, @Nullable ImmutableList<String> schema, @Nullable Key key) {
+      Location location,
+      @Nullable ImmutableList<String> schema,
+      @Nullable StarlarkCallable init,
+      @Nullable Key key) {
     this.location = location;
     this.schema = schema;
+    this.init = init;
     this.key = key;
   }
 
+  private static Object[] toNamedArgs(Object value, String descriptionForError)
+      throws EvalException {
+    Dict<String, Object> kwargs = Dict.cast(value, String.class, Object.class, descriptionForError);
+    Object[] named = new Object[2 * kwargs.size()];
+    int i = 0;
+    for (Map.Entry<String, Object> e : kwargs.entrySet()) {
+      named[i++] = e.getKey();
+      named[i++] = e.getValue();
+    }
+    return named;
+  }
+
   @Override
   public Object fastcall(StarlarkThread thread, Object[] positional, Object[] named)
+      throws InterruptedException, EvalException {
+    if (init == null) {
+      return fastcallRawConstructor(thread, positional, named);
+    }
+
+    Object initResult = Starlark.fastcall(thread, init, positional, named);
+    return StarlarkInfo.createFromNamedArgs(
+        this,
+        toNamedArgs(initResult, "return value of provider init()"),
+        schema,
+        thread.getCallerLocation());
+  }
+
+  private Object fastcallRawConstructor(StarlarkThread thread, Object[] positional, Object[] named)
       throws EvalException {
     if (positional.length > 0) {
       throw Starlark.errorf("%s: unexpected positional arguments", getName());
     }
     return StarlarkInfo.createFromNamedArgs(this, named, schema, thread.getCallerLocation());
   }
 
+  private static final class RawConstructor implements StarlarkCallable {
+    private final StarlarkProvider provider;
+
+    private RawConstructor(StarlarkProvider provider) {
+      this.provider = provider;
+    }
+
+    @Override
+    public Object fastcall(StarlarkThread thread, Object[] positional, Object[] named)
+        throws EvalException {
+      return provider.fastcallRawConstructor(thread, positional, named);
+    }
+
+    @Override
+    public String getName() {
+      StringBuilder name = new StringBuilder("<raw constructor");
+      if (provider.isExported()) {
+        name.append(" for ").append(provider.getName());
+      }
+      name.append(">");
+      return name.toString();
+    }
+
+    @Override
+    public Location getLocation() {
+      return provider.location;
+    }
+  }
+
+  public StarlarkCallable createRawConstructor() {
+    return new RawConstructor(this);
+  }
+
+  @Nullable
+  @VisibleForTesting
+  public StarlarkCallable getInit() {
+    return init;
+  }
+
   @Override
   public Location getLocation() {
     return location;