Add docstrings for the new flags API and update the flags codelab documentation.

ashishenoyp · copybara-github · commit b1d726dce38e · 2023-08-10T09:41:54.000-07:00
PiperOrigin-RevId: 555528764
diff --git a/docs/flags_code_lab.md b/docs/flags_code_lab.md
@@ -4,9 +4,40 @@
 
 You can easily fiddle with your configuration using command line flags, thanks
 to Fiddle's absl_flags integration! This code lab will describe how it all
-works. See also the [complete working example][example].
+works. Configuration of fiddle config objects via command line arguments is
+supported using 2 APIs:
 
-[example]: http://github.com/google/fiddle/tree/main/fiddle/absl_flags/example
+| API        | Purpose                                                         |
+| ---------- | --------------------------------------------------------------- |
+| New API    | Defines custom configurations per binary using the API          |
+:            : `DEFINE_fiddle_config()` which returns a built config object    :
+:            : handle after applying all the command line overrides in order.  :
+:            : The usage of this API is more intuitive than the legacy API,    :
+:            : and it provides the ability to define custom overrides per      :
+:            : binary. Additionally, the overrides are applied in order, which :
+:            : is a more intuitive user experience than the current order      :
+:            : followed by the legacy API                                      :
+| Legacy API | Invoked via `create_buildable_from_flags()` that returns a      |
+:            : built config object. Command line overrides are NOT applied in  :
+:            : order; all fiddlers are applied first, followed by all tags,    :
+:            : followed by all overrides.                                      :
+
+> NOTE: New usages of the legacy flags API are discouraged and users should
+> migrate their legacy usage to the new API.
+
+See some working examples of the APIs below.
+
+<section class="tabs" markdown=1>
+
+### New API {.new-tab}
+
+[example](http://github.com/google/fiddle/tree/main/fiddle/_src/absl_flags/sample_test_binary.py)
+
+### Legacy API {.new-tab}
+
+[example](http://github.com/google/fiddle/tree/main/fiddle/absl_flags/example)
+
+</section>
 
 [TOC]
 
@@ -36,6 +67,30 @@ Fiddle pattern includes:
 
 When our example program is executed, the following steps occur:
 
+<section class="tabs" markdown=1>
+
+### New API {.new-tab}
+
+1.  **Launch**: We run our program on the command line:
+
+    ```sh
+    python3 -m fiddle._src.absl_flags.sample_test_binary \
+    --sample_config config:base_experiment \ --sample_config
+    fiddler:'set_dtypes(dtype="float64")' \ --sample_config
+    set:decoder.mlp.use_bias=True \ --sample_config
+    set:decoder.mlp.dtype='"float16"'
+    ```
+
+2.  **Flag Parsing**: The custom Fiddle flag parser parses Fiddle-related flags
+    from the command line, applying any overrides in the order specified in the
+    command line, and returns a built object `_SAMPLE_FLAG.value` that has all
+    the overrides applied.
+
+3.  **Business logic**: `main` calls arbitrary functions on the built objects to
+    carry out whatever task your application has been designed to do.
+
+### Legacy API {.new-tab}
+
 1.  **Launch**: We run our program on the command line:
 
     ```sh
@@ -84,30 +139,75 @@ When our example program is executed, the following steps occur:
     case of the example, `main` calls `runner.run()` to (pretend to) train a
     neural network.
 
+</section>
+
 ## Flag Syntax
 
 The Fiddle flag integration supports the following flag syntax:
 
--   **Base Config**: The base configuration function is specified with the flag
-    `--fdl_config`. Example: `--fdl_config=base`. Alternatively, a
-    JSON-serialized configuration can be read from a file via with the flag
-    `--fdl_config_file`. Example: `--fdl_config_file='/some/path/config.json'`.
+-   **Base Config**: The base configuration function is specified with the flag:
+
+<section class="tabs" markdown=1>
+
+### New API {.new-tab}
+
+that was set as the `name` argument for `DEFINE_fiddle_config` and the command
+`config`. For example, if the flag object was instantiated as
+`DEFINE_fiddle_config(name="my_flag", ...)`, then the base config is specified
+by using `--my_flag
+config:some_function_returning_fiddle_config_to_be_overridden()`.
+
+### Legacy API {.new-tab}
+
+`--fdl_config`. Example: `--fdl_config=base`. Alternatively, a JSON-serialized
+configuration can be read from a file via with the flag `--fdl_config_file`.
+Example: `--fdl_config_file='/some/path/config.json'`.
+
+</section>
 
 -   **Fiddlers**: Fiddlers are specified on the command line with the
-    `--fiddler=` flag. This flag can be specified multiple times. Example:
-    `--fiddler=swap_weight_and_biases --fiddler=other_fiddler`.
+
+<section class="tabs" markdown=1>
+
+### New API {.new-tab}
+
+command `fiddler` after the `name` argument for `DEFINE_fiddle_config`. For
+example, if the flag object was instantiated as
+`DEFINE_fiddle_config(name="my_flag", ...)` then the fiddlers would be invoked
+like `--my_flag fiddler:name_of_fiddler(value="new_value")`.
+
+### Legacy API {.new-tab}
+
+`--fiddler=` flag. This flag can be specified multiple times. Example:
+`--fiddler=swap_weight_and_biases --fiddler=other_fiddler`.
+
+</section>
 
 -   **Specific Overrides**: Specific overrides allow you to specify specific
     values to arbitrary fields on the command line. The syntax is
-    `--fdl.dotted.path.of.fields=3`, where everything after the `fdl.` prefix
-    corresponds to the name of a field in the Fiddle configuration object
-    corresponding to exactly the same Python code. For example, if (in Python)
-    we wanted to set the value of a nested field to 15, I might write:
-    `cfg.model.dense1.parameters = 15`. The corresponding syntax on the command
-    line would be: `--fdl.model.dense1.parameters=15`. Due to shell escaping, to
-    specify a string value, you often need to use two nested quotes, or escape
-    the outer quotes (depending on your shell). For example:
-    `--fdl.data.filename='"other.txt"'` (or equivalently:
-    `--fdl.data.filename=\"other.txt\"`). Only "literal" values may be specified
-    on the command line like this; if you'd like to set a complex value, please
-    write a fiddler and invoke it with the previous Fiddlers syntax.
+
+<section class="tabs" markdown=1>
+
+### New API {.new-tab}
+
+the command `set` after the `name` argument for `DEFINE_fiddle_config`. For
+example, if the flag object was instantiated as
+`DEFINE_fiddle_config(name="my_flag", ...)`, then the specific overrides are
+specified using `--my_flag set:some_attr.some_sub_attr=some_value`.
+
+### Legacy API {.new-tab}
+
+`--fdl.dotted.path.of.fields=3`, where everything after the `fdl.` prefix
+corresponds to the name of a field in the Fiddle configuration object
+corresponding to exactly the same Python code. For example, if (in Python) we
+wanted to set the value of a nested field to 15, I might write:
+`cfg.model.dense1.parameters = 15`. The corresponding syntax on the command line
+would be: `--fdl.model.dense1.parameters=15`. Due to shell escaping, to specify
+a string value, you often need to use two nested quotes, or escape the outer
+quotes (depending on your shell). For example:
+`--fdl.data.filename='"other.txt"'` (or equivalently:
+`--fdl.data.filename=\"other.txt\"`). Only "literal" values may be specified on
+the command line like this; if you'd like to set a complex value, please write a
+fiddler and invoke it with the previous Fiddlers syntax.
+
+</section>
diff --git a/fiddle/_src/absl_flags/flags.py b/fiddle/_src/absl_flags/flags.py
@@ -39,7 +39,7 @@
 _F = TypeVar("_F")
 
 
-class FiddleFlag(flags.MultiFlag):
+class _FiddleFlag(flags.MultiFlag):
   """ABSL flag class for a Fiddle config flag."""
 
   def __init__(
@@ -127,8 +127,63 @@ def DEFINE_fiddle_config(  # pylint: disable=invalid-name
     default_module: Optional[types.ModuleType] = None,
     flag_values: flags.FlagValues = flags.FLAGS,
 ) -> flags.FlagHolder[Any]:
+  r"""Declare and define a fiddle command line flag object.
+
+  When used in a python binary, after the flags have been parsed from the
+  command line, this command line flag object will have the `fdl.Config` object
+  built.
+
+  Example usage in a python binary:
+  ```
+  .... other imports ...
+  from fiddle import absl_flags as fdl_flags
+
+  _MY_FLAG = fdl_flags.DEFINE_fiddle_config(
+      "my_config",
+      help_string="My binary's fiddle config handle",
+      default_module=sys.modules[__name__],
+  )
+
+  def base_config() -> fdl.Config:
+    return some_import.fixture.as_buildable()
+
+  def set_attributes(config, value: str):
+    config.some_attr = value
+    return config
+
+  def main(argv) -> None:
+    if len(argv) > 1:
+      raise app.UsageError("Too many command-line arguments.")
+    # _MY_FLAG.value contains the config object, built from `base_config()`
+    # with any command line flags and overrides applied in the order passed in
+    # the command line.
+    some_import.do_something(_MY_FLAG.value.some_attr)
+
+  if __name__ == "__main__":
+    app.run(main)
+  ```
+
+  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
+
+  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.
+
+  Args:
+    name: name of the command line flag.
+    default: default value of the flag.
+    help_string: help string describing what the flag does.
+    default_module: the python module where this flag is defined.
+    flag_values: the ``FlagValues`` instance with which the flag will be
+      registered. This should almost never need to be overridden.
+
+  Returns:
+    A handle to defined flag.
+  """
   return flags.DEFINE_flag(
-      FiddleFlag(
+      _FiddleFlag(
           name=name,
           default_module=default_module,
           default=default,
