recipe_modules/gsutil: Add `dry_run` kwarg

This kwarg will display the command that would have been run, without
actually running it. I plan to use this kwarg on some ChromeOS staging
builders.

BUG=b:270142110
TEST=./recipes.py test train

Change-Id: I20194152e305dc6bae71a58b94de71d414839643
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/tools/depot_tools/+/4382316
Reviewed-by: Gavin Mak <gavinmak@google.com>
Auto-Submit: Greg Edelston <gredelston@google.com>
Commit-Queue: Greg Edelston <gredelston@google.com>
Reviewed-by: Aravind Vasudevan <aravindvasudev@google.com>

recipes/README.recipes.md

@@ -640,7 +640,7 @@ PYTHON_VERSION_COMPATIBILITY: PY3
 
 #### **class [GSUtilApi](/recipes/recipe_modules/gsutil/api.py#10)([RecipeApi][recipe_engine/wkt/RecipeApi]):**
 
-— **def [\_\_call\_\_](/recipes/recipe_modules/gsutil/api.py#21)(self, cmd, name=None, use_retry_wrapper=True, version=None, parallel_upload=False, multithreaded=False, infra_step=True, \*\*kwargs):**
+— **def [\_\_call\_\_](/recipes/recipe_modules/gsutil/api.py#21)(self, cmd, name=None, use_retry_wrapper=True, version=None, parallel_upload=False, multithreaded=False, infra_step=True, dry_run=False, \*\*kwargs):**
 
 A step to run arbitrary gsutil commands.
 
@@ -657,10 +657,12 @@ Args:
       options first (see 'gsutil help options').
   * name (str) - Name of the step to use. Defaults to the first non-flag
       token in the cmd.
+  * dry_run (bool): If True, don't actually run the step; just log what
+      the step would have been.
 
-— **def [cat](/recipes/recipe_modules/gsutil/api.py#115)(self, url, args=None, \*\*kwargs):**
+— **def [cat](/recipes/recipe_modules/gsutil/api.py#129)(self, url, args=None, \*\*kwargs):**
 
-&emsp; **@contextlib.contextmanager**<br>&mdash; **def [configure\_gsutil](/recipes/recipe_modules/gsutil/api.py#169)(self, \*\*kwargs):**
+&emsp; **@contextlib.contextmanager**<br>&mdash; **def [configure\_gsutil](/recipes/recipe_modules/gsutil/api.py#183)(self, \*\*kwargs):**
 
 Temporarily configures the behavior of gsutil.
 
@@ -672,23 +674,23 @@ possible configurations.
 Args:
   kwargs: Every keyword arg is treated as config line in the temp Boto file.
 
-&mdash; **def [copy](/recipes/recipe_modules/gsutil/api.py#129)(self, source_bucket, source, dest_bucket, dest, args=None, link_name='gsutil.copy', metadata=None, unauthenticated_url=False, \*\*kwargs):**
+&mdash; **def [copy](/recipes/recipe_modules/gsutil/api.py#143)(self, source_bucket, source, dest_bucket, dest, args=None, link_name='gsutil.copy', metadata=None, unauthenticated_url=False, \*\*kwargs):**
 
-&mdash; **def [download](/recipes/recipe_modules/gsutil/api.py#101)(self, bucket, source, dest, args=None, \*\*kwargs):**
+&mdash; **def [download](/recipes/recipe_modules/gsutil/api.py#115)(self, bucket, source, dest, args=None, \*\*kwargs):**
 
-&mdash; **def [download\_url](/recipes/recipe_modules/gsutil/api.py#108)(self, url, dest, args=None, \*\*kwargs):**
+&mdash; **def [download\_url](/recipes/recipe_modules/gsutil/api.py#122)(self, url, dest, args=None, \*\*kwargs):**
 
 &emsp; **@property**<br>&mdash; **def [gsutil\_py\_path](/recipes/recipe_modules/gsutil/api.py#17)(self):**
 
-&mdash; **def [list](/recipes/recipe_modules/gsutil/api.py#148)(self, url, args=None, \*\*kwargs):**
+&mdash; **def [list](/recipes/recipe_modules/gsutil/api.py#162)(self, url, args=None, \*\*kwargs):**
 
-&mdash; **def [remove\_url](/recipes/recipe_modules/gsutil/api.py#162)(self, url, args=None, \*\*kwargs):**
+&mdash; **def [remove\_url](/recipes/recipe_modules/gsutil/api.py#176)(self, url, args=None, \*\*kwargs):**
 
-&mdash; **def [signurl](/recipes/recipe_modules/gsutil/api.py#155)(self, private_key_file, bucket, dest, args=None, \*\*kwargs):**
+&mdash; **def [signurl](/recipes/recipe_modules/gsutil/api.py#169)(self, private_key_file, bucket, dest, args=None, \*\*kwargs):**
 
-&mdash; **def [stat](/recipes/recipe_modules/gsutil/api.py#122)(self, url, args=None, \*\*kwargs):**
+&mdash; **def [stat](/recipes/recipe_modules/gsutil/api.py#136)(self, url, args=None, \*\*kwargs):**
 
-&mdash; **def [upload](/recipes/recipe_modules/gsutil/api.py#84)(self, source, bucket, dest, args=None, link_name='gsutil.upload', metadata=None, unauthenticated_url=False, \*\*kwargs):**
+&mdash; **def [upload](/recipes/recipe_modules/gsutil/api.py#98)(self, source, bucket, dest, args=None, link_name='gsutil.upload', metadata=None, unauthenticated_url=False, \*\*kwargs):**
 ### *recipe_modules* / [osx\_sdk](/recipes/recipe_modules/osx_sdk)
 
 [DEPS](/recipes/recipe_modules/osx_sdk/__init__.py#7): [recipe\_engine/cipd][recipe_engine/recipe_modules/cipd], [recipe\_engine/context][recipe_engine/recipe_modules/context], [recipe\_engine/json][recipe_engine/recipe_modules/json], [recipe\_engine/path][recipe_engine/recipe_modules/path], [recipe\_engine/platform][recipe_engine/recipe_modules/platform], [recipe\_engine/step][recipe_engine/recipe_modules/step], [recipe\_engine/version][recipe_engine/recipe_modules/version]

recipes/recipe_modules/gsutil/api.py

@@ -18,8 +18,15 @@ class GSUtilApi(recipe_api.RecipeApi):
   def gsutil_py_path(self):
     return self.repo_resource('gsutil.py')
 
-  def __call__(self, cmd, name=None, use_retry_wrapper=True, version=None,
-               parallel_upload=False, multithreaded=False, infra_step=True,
+  def __call__(self,
+               cmd,
+               name=None,
+               use_retry_wrapper=True,
+               version=None,
+               parallel_upload=False,
+               multithreaded=False,
+               infra_step=True,
+               dry_run=False,
                **kwargs):
     """A step to run arbitrary gsutil commands.
 
@@ -36,6 +43,8 @@ class GSUtilApi(recipe_api.RecipeApi):
           options first (see 'gsutil help options').
       * name (str) - Name of the step to use. Defaults to the first non-flag
           token in the cmd.
+      * dry_run (bool): If True, don't actually run the step; just log what
+          the step would have been.
     """
     if name:
       full_name = 'gsutil ' + name
@@ -79,6 +88,11 @@ class GSUtilApi(recipe_api.RecipeApi):
       cmd_prefix.append('--')
 
     exec_cmd = ['python3', '-u', gsutil_path] + cmd_prefix + cmd
+    if dry_run:
+      return self.m.step.empty(full_name,
+                               step_text='Pretending to run gsutil command',
+                               log_text=' '.join((str(i) for i in exec_cmd)),
+                               log_name='command')
     return self.m.step(full_name, exec_cmd, infra_step=infra_step, **kwargs)
 
   def upload(self, source, bucket, dest, args=None, link_name='gsutil.upload',

recipes/recipe_modules/gsutil/examples/full.expected/basic.json

@@ -241,6 +241,15 @@
     "infra_step": true,
     "name": "gsutil stat"
   },
+  {
+    "cmd": [],
+    "name": "gsutil read remote file",
+    "~followup_annotations": [
+      "@@@STEP_TEXT@Pretending to run gsutil command@@@",
+      "@@@STEP_LOG_LINE@command@python3 -u RECIPE_MODULE[depot_tools::gsutil]/resources/gsutil_smart_retry.py -- RECIPE_REPO[depot_tools]/gsutil.py -m ---- cat gs://example/foo@@@",
+      "@@@STEP_LOG_END@command@@@"
+    ]
+  },
   {
     "name": "$result"
   }

recipes/recipe_modules/gsutil/examples/full.py

@@ -90,5 +90,12 @@ def RunSteps(api):
 
   api.gsutil.stat('gs://%s/foo' % bucket)
 
+  # Run in dry-run mode.
+  api.gsutil.cat('gs://%s/foo' % bucket,
+                 name='read remote file',
+                 multithreaded=True,
+                 dry_run=True)
+
+
 def GenTests(api):
   yield api.test('basic')