Cleanup bot_update TurboCI code.

This adds and fixes documentation for the TurboCI check handler types
and the turboci_check_id parameter to bot_update.ensure_checkout.
Additionally, the gclient_config to _TurboCICheckHandler.create and
_EnabledTurboCiCheckHandler.__init__ was removed because the gclient
config wasn't being used.

Bug: b:443496677
Change-Id: I4acc3170522735e63062bed47f555aabcd2a4304
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/tools/depot_tools/+/7172970
Auto-Submit: Garrett Beaty <gbeaty@google.com>
Commit-Queue: Garrett Beaty <gbeaty@google.com>
Reviewed-by: Robbie Iannucci <iannucci@google.com>

recipes/README.recipes.md

@@ -59,18 +59,18 @@
 
 Recipe module to ensure a checkout is consistent on a bot.
 
-#### **class [BotUpdateApi](/recipes/recipe_modules/bot_update/api.py#218)([RecipeApi][recipe_engine/wkt/RecipeApi]):**
+#### **class [BotUpdateApi](/recipes/recipe_modules/bot_update/api.py#266)([RecipeApi][recipe_engine/wkt/RecipeApi]):**
 
-— **def [\_\_call\_\_](/recipes/recipe_modules/bot_update/api.py#227)(self, name, cmd, \*\*kwargs):**
+— **def [\_\_call\_\_](/recipes/recipe_modules/bot_update/api.py#275)(self, name, cmd, \*\*kwargs):**
 
 Wrapper for easy calling of bot_update.
 
-— **def [deapply\_patch](/recipes/recipe_modules/bot_update/api.py#851)(self, bot_update_result):**
+— **def [deapply\_patch](/recipes/recipe_modules/bot_update/api.py#899)(self, bot_update_result):**
 
 Deapplies a patch, taking care of DEPS and solution revisions properly.
     
 
-— **def [ensure\_checkout](/recipes/recipe_modules/bot_update/api.py#338)(self, gclient_config=None, \*, suffix=None, patch=True, update_presentation=True, patch_root=None, with_branch_heads=False, with_tags=False, no_fetch_tags=False, refs=None, clobber=False, root_solution_revision=None, gerrit_no_reset=False, gerrit_no_rebase_patch_ref=False, assert_one_gerrit_change=True, patch_refs=None, ignore_input_commit=False, add_blamelists=False, set_output_commit=False, step_test_data=None, enforce_fetch=False, download_topics=False, recipe_revision_overrides=None, step_tags=None, clean_ignored=False, turboci_check_id: str='', \*\*kwargs):**
+— **def [ensure\_checkout](/recipes/recipe_modules/bot_update/api.py#386)(self, gclient_config=None, \*, suffix=None, patch=True, update_presentation=True, patch_root=None, with_branch_heads=False, with_tags=False, no_fetch_tags=False, refs=None, clobber=False, root_solution_revision=None, gerrit_no_reset=False, gerrit_no_rebase_patch_ref=False, assert_one_gerrit_change=True, patch_refs=None, ignore_input_commit=False, add_blamelists=False, set_output_commit=False, step_test_data=None, enforce_fetch=False, download_topics=False, recipe_revision_overrides=None, step_tags=None, clean_ignored=False, turboci_check_id: str='', \*\*kwargs):**
 
 Args:
   * gclient_config: The gclient configuration to use when running bot_update.
@@ -113,7 +113,7 @@ Args:
     if a non-empty value is provided and the gclient config doesn't have
     exactly 1 solution.
 
-— **def [get\_project\_revision\_properties](/recipes/recipe_modules/bot_update/api.py#828)(self, project_name, gclient_config=None):**
+— **def [get\_project\_revision\_properties](/recipes/recipe_modules/bot_update/api.py#876)(self, project_name, gclient_config=None):**
 
 Returns all property names used for storing the checked-out revision of
 a given project.
@@ -127,14 +127,14 @@ Args:
 Returns (list of str): All properties that'll hold the checked-out revision
     of the given project. An empty list if no such properties exist.
 
-&emsp; **@property**<br>&mdash; **def [last\_returned\_properties](/recipes/recipe_modules/bot_update/api.py#246)(self):**
+&emsp; **@property**<br>&mdash; **def [last\_returned\_properties](/recipes/recipe_modules/bot_update/api.py#294)(self):**
 
-&mdash; **def [resolve\_fixed\_revision](/recipes/recipe_modules/bot_update/api.py#779)(self, bot_update_result, name):**
+&mdash; **def [resolve\_fixed\_revision](/recipes/recipe_modules/bot_update/api.py#827)(self, bot_update_result, name):**
 
 Sets a fixed revision for a single dependency using project revision
 properties.
 
-&mdash; **def [step\_name](/recipes/recipe_modules/bot_update/api.py#868)(self, patch, suffix):**
+&mdash; **def [step\_name](/recipes/recipe_modules/bot_update/api.py#916)(self, patch, suffix):**
 ### *recipe_modules* / [depot\_tools](/recipes/recipe_modules/depot_tools)
 
 [DEPS](/recipes/recipe_modules/depot_tools/__init__.py#6): [recipe\_engine/cipd][recipe_engine/recipe_modules/cipd], [recipe\_engine/context][recipe_engine/recipe_modules/context], [recipe\_engine/platform][recipe_engine/recipe_modules/platform], [recipe\_engine/runtime][recipe_engine/recipe_modules/runtime]

recipes/recipe_modules/bot_update/api.py

@@ -70,19 +70,43 @@ class Result:
 
 
 class _TurboCICheckHandler(abc.ABC):
+  """Handler for creating and updating a TurboCI source check.
+
+  Getting a handler should be done by calling
+  _TurboCICheckHandler.create with the ID to use for the check. An empty
+  check ID will result in a no-op handler.
+
+  Before performing the checkout, set_revisions should be called to
+  provide information about the known revisions being checked out and if
+  a patch is being applied, set_gerrit_change should be called to
+  provide information about the change. After those calls are made,
+  create_check should be called to create the check in TurboCI.
+
+  After performing the checkout, set_result should be called to write
+  results into the check and finalize it.
+  """
 
   @staticmethod
-  def create(api, check_id: str, gclient_config):
+  def create(api, check_id: str):
+    """Create a _TurboCiCheckHandler.
+
+    Args:
+      check_id: The ID of the TurboCI check that the handler should
+        create. If empty, a no-op handler will be returned.
+    """
     if not check_id:
       return _DisabledTurboCICheckHandler()
 
-    return _EnabledTurboCiCheckHandler(api, check_id, gclient_config)
+    return _EnabledTurboCiCheckHandler(api, check_id)
 
   @abc.abstractmethod
   def set_gerrit_change(self, gerrit_change: common_pb2.GerritChange,
                         patch_root: str) -> None:
     """Sets the gerrit change that is being checked out.
 
+    Information about the change will be added to the check that is
+    created.
+
     Args:
       gerrit_change: The gerrit change that is being checked out.
       patch_root: The path to the repository that is being patched,
@@ -96,14 +120,39 @@ class _TurboCICheckHandler(abc.ABC):
       revisions: collections.abc.Mapping[str, str],
       refs: collections.abc.Mapping[str, str],
   ) -> None:
+    """Set the revisions to be checked out.
+
+    Information about the revisions will be added to the check that is
+    created.
+
+    Args:
+      revisions: Mapping from the solution name/checkout-relative path
+        of a repo to the revision that the repo will be checked out
+        from.
+      refs: Mapping from the solution name/checkout-relative path of a
+        repo to the ref that the repo will be checked out from.
+    """
     raise NotImplementedError()  # pragma: no cover
 
   @abc.abstractmethod
   def create_check(self) -> None:
+    """Create the TurboCI check.
+
+    A check will be created with kind SOURCE and state PLANNED. The
+    check will contain a GobSourceCheckOptions option that contains the
+    revision information specified by set_revisions and the change
+    information specified by set_gerrit_change.
+    """
     raise NotImplementedError()  # pragma: no cover
 
   @abc.abstractmethod
   def set_result(self, result: Result) -> None:
+    """Set the results on the TurboCI check.
+
+    The check will have a GobSourceCheckResults result added that
+    contains details about the change that was applied (if any) and be
+    moved to the FINAL state.
+    """
     raise NotImplementedError()  # pragma: no cover
 
 
@@ -129,12 +178,11 @@ class _DisabledTurboCICheckHandler(_TurboCICheckHandler):
 
 
 class _EnabledTurboCiCheckHandler(_TurboCICheckHandler):
-  """A no-op implementation of _TurboCICheckHandler."""
+  """_TurboCICheckHandler that actually creates a check in TurboCI."""
 
-  def __init__(self, api, check_id: str, gclient_config):
+  def __init__(self, api, check_id: str):
     self._api = api
     self._check_id = check_id
-    self._gclient_config = gclient_config
     self._gerrit_change: common_pb2.GerritChange | None = None
     self._source_check_options = GobSourceCheckOptions()
 
@@ -418,7 +466,7 @@ class BotUpdateApi(recipe_api.RecipeApi):
     assert cfg is not None, (
         'missing gclient_config or forgot api.gclient.set_config(...) before?')
 
-    check_handler = _TurboCICheckHandler.create(self, turboci_check_id, cfg)
+    check_handler = _TurboCICheckHandler.create(self, turboci_check_id)
 
     # Construct our bot_update command.  This basically be inclusive of
     # everything required for bot_update to know: