Introduce immutable_fiddler as part of new flags API.

An immutable fiddler function is one that doesn't mutate the original
  `fdl.Buildable` object that's passed into it and instead returns a new
  `fdl.Buildable` built from the original `fdl.Buildable` after applying the
  transform `fn`. It is different from a
  mutable fiddler function that directly mutates the original `fdl.Buildable`
  object. Immutable fiddlers are useful when using various util functions such
  as `daglish.MemoizedTraversal.run()` that return a new `fdl.Buildable` object.

PiperOrigin-RevId: 557925124

Author: ashishenoyp

docs/flags_code_lab.md

@@ -61,7 +61,12 @@ Fiddle pattern includes:
 -   **Base Configuration**: A base configuration function is a function without
     required arguments (a nullary function) that returns a `fdl.Buildable`.
 -   **Fiddler**: A fiddler is a unary function that takes a `fdl.Buildable` and
-    mutates it. (A fiddler returns `None`.)
+    applies some transformations. If the fiddler returns `None`, then it is
+    assumed the input `fdl.Buildable` was mutated by the fiddler, and the
+    mutated input will be passed on to further flag operations. If the fiddler
+    returns a non-`None` value (e.g., a new `fdl.Buildable` obtained from
+    applying a `daglish` traversal routine), the return value of the fiddler is
+    passed on instead.
 
 ## Life of a flag-augmented Fiddle program
 

fiddle/_src/absl_flags/flags.py

@@ -80,7 +80,21 @@ def _apply_fiddler(self, cfg: config.Buildable, expression: str):
         self.allow_imports,
         "Could not init a buildable from",
     )
-    return fiddler(cfg, *call_expr.args, **call_expr.kwargs)
+
+    # An immutable fiddler function is one that doesn't mutate the original
+    # `fdl.Buildable` object that's passed into it and instead returns a new
+    # `fdl.Buildable` built from the original `fdl.Buildable` after applying the
+    # transform `fiddler`. It is different from a mutable fiddler function that
+    # directly mutates the original `fdl.Buildable` object. Immutable fiddlers
+    # are useful when using various util functions such as
+    # `daglish.MemoizedTraversal.run()` that return a new `fdl.Buildable`
+    # object. Immutable fiddler functions return a non-None value.
+    new_cfg = fiddler(cfg, *call_expr.args, **call_expr.kwargs)
+
+    # If the fiddler is immutable, then return the transformed `fdl.Buildable`
+    # passed into the function. Else, return the mutated original
+    # `fdl.Buildable` object.
+    return new_cfg if new_cfg is not None else cfg
 
   def parse(self, argument):
     parsed = self._parse(argument)
@@ -164,9 +178,9 @@ def main(argv) -> None:
   ```
 
   Invoking the above binary with:
-  python3 -m path.to.my.binary --my_config config:base_config \
-  --my_config fiddler:'set_attributes(value="float64")' --my_config \
-  set:some_other_attr.enable=True
+  python3 -m path.to.my.binary --my_config=config:base_config \
+  --my_config=fiddler:'set_attributes(value="float64")' \
+  --my_config=set:some_other_attr.enable=True
 
   results in the `_MY_FLAG.value` set to the built config object with all the
   command line flags applied in the order they were passed in.