Add a method to the git API for running git number.

Change-Id: Ieac13aac86df1c3e759f5aa66015ee6a3ac5c826
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/tools/depot_tools/+/3307495
Commit-Queue: Garrett Beaty <gbeaty@google.com>
Auto-Submit: Garrett Beaty <gbeaty@google.com>
Reviewed-by: Gavin Mak <gavinmak@google.com>

recipes/README.recipes.md

@@ -27,6 +27,7 @@
   * [gclient:tests/sync_failure](#recipes-gclient_tests_sync_failure) (Python3 ✅)
   * [gerrit:examples/full](#recipes-gerrit_examples_full) (Python3 ✅)
   * [git:examples/full](#recipes-git_examples_full) (Python3 ✅)
+  * [git:tests/number](#recipes-git_tests_number) (Python3 ✅)
   * [git_cl:examples/full](#recipes-git_cl_examples_full) (Python3 ✅)
   * [gitiles:examples/full](#recipes-gitiles_examples_full) (Python3 ✅)
   * [gitiles:tests/parse_repo_url](#recipes-gitiles_tests_parse_repo_url) (Python3 ✅)
@@ -490,6 +491,23 @@ Args:
   * upstream_current (bool): whether to use '--upstream_current'.
   * kwargs: Forwarded to '__call__'.
 
+— **def [number](/recipes/recipe_modules/git/api.py#427)(self, commitrefs=None, test_values=None):**
+
+Computes the generation number of some commits.
+
+Args:
+  * commitrefs (list[str]): A list of commit references. If none are
+    provided, the generation number for HEAD will be retrieved.
+  * test_values (list[str]): A list of numbers to use as the return
+    value during tests. It is an error if the length of the list
+    does not match the number of commitrefs (1 if commitrefs is not
+    provided).
+
+Returns:
+A list of strings containing the generation numbers of the commits.
+If non-empty commitrefs was provided, the order of the returned
+numbers will correspond to the order of the provided commitrefs.
+
 — **def [rebase](/recipes/recipe_modules/git/api.py#332)(self, name_prefix, branch, dir_path, remote_name=None, \*\*kwargs):**
 
 Runs rebase HEAD onto branch
@@ -1026,6 +1044,13 @@ PYTHON_VERSION_COMPATIBILITY: PY2+3
 PYTHON_VERSION_COMPATIBILITY: PY2+3
 
 — **def [RunSteps](/recipes/recipe_modules/git/examples/full.py#20)(api):**
+### *recipes* / [git:tests/number](/recipes/recipe_modules/git/tests/number.py)
+
+[DEPS](/recipes/recipe_modules/git/tests/number.py#9): [git](#recipe_modules-git), [recipe\_engine/assertions][recipe_engine/recipe_modules/assertions], [recipe\_engine/properties][recipe_engine/recipe_modules/properties]
+
+PYTHON_VERSION_COMPATIBILITY: PY2+3
+
+— **def [RunSteps](/recipes/recipe_modules/git/tests/number.py#16)(api):**
 ### *recipes* / [git\_cl:examples/full](/recipes/recipe_modules/git_cl/examples/full.py)
 
 [DEPS](/recipes/recipe_modules/git_cl/examples/full.py#11): [git\_cl](#recipe_modules-git_cl), [recipe\_engine/path][recipe_engine/recipe_modules/path], [recipe\_engine/raw\_io][recipe_engine/recipe_modules/raw_io], [recipe\_engine/step][recipe_engine/recipe_modules/step]

recipes/recipe_modules/git/api.py

@@ -423,3 +423,35 @@ class GitApi(recipe_api.RecipeApi):
       name = 'git new-branch %s' % branch
     with self.m.context(env=env):
       return self(*args, name=name, **kwargs)
+
+  def number(self, commitrefs=None, test_values=None):
+    """Computes the generation number of some commits.
+
+    Args:
+      * commitrefs (list[str]): A list of commit references. If none are
+        provided, the generation number for HEAD will be retrieved.
+      * test_values (list[str]): A list of numbers to use as the return
+        value during tests. It is an error if the length of the list
+        does not match the number of commitrefs (1 if commitrefs is not
+        provided).
+
+    Returns:
+    A list of strings containing the generation numbers of the commits.
+    If non-empty commitrefs was provided, the order of the returned
+    numbers will correspond to the order of the provided commitrefs.
+    """
+
+    def step_test_data():
+      refs = commitrefs or ['HEAD']
+      if test_values:
+        assert len(test_values) == len(refs)
+      values = test_values or range(3000, 3000 + len(refs))
+      output = '\n'.join(str(v) for v in values)
+      return self.m.raw_io.test_api.stream_output_text(output)
+
+    args = ['number']
+    args.extend(commitrefs or [])
+    step_result = self(*args,
+                       stdout=self.m.raw_io.output_text(add_output_log=True),
+                       step_test_data=step_test_data)
+    return [l.strip() for l in step_result.stdout.strip().splitlines()]

recipes/recipe_modules/git/tests/number.py

@@ -0,0 +1,62 @@
+# Copyright 2013 The Chromium Authors. All rights reserved.
+# Use of this source code is governed by a BSD-style license that can be
+# found in the LICENSE file.
+
+from recipe_engine import post_process
+
+PYTHON_VERSION_COMPATIBILITY = 'PY2+3'
+
+DEPS = [
+    'git',
+    'recipe_engine/assertions',
+    'recipe_engine/properties',
+]
+
+
+def RunSteps(api):
+  numbers = api.git.number(
+      commitrefs=api.properties.get('commitrefs'),
+      test_values=api.properties.get('test_values'),
+  )
+  expected_numbers = api.properties['expected_numbers']
+  api.assertions.assertSequenceEqual(numbers, expected_numbers)
+
+
+def GenTests(api):
+  yield api.test(
+      'basic',
+      api.properties(expected_numbers=['3000']),
+      api.post_check(post_process.StatusSuccess),
+      api.post_process(post_process.DropExpectation),
+  )
+
+  yield api.test(
+      'commitrefs',
+      api.properties(
+          commitrefs=['rev-1', 'rev-2'],
+          expected_numbers=['3000', '3001'],
+      ),
+      api.post_check(post_process.StatusSuccess),
+      api.post_process(post_process.DropExpectation),
+  )
+
+  yield api.test(
+      'basic-with-test-values',
+      api.properties(
+          test_values=[42],
+          expected_numbers=['42'],
+      ),
+      api.post_check(post_process.StatusSuccess),
+      api.post_process(post_process.DropExpectation),
+  )
+
+  yield api.test(
+      'commitrefs-with-test-values',
+      api.properties(
+          test_values=[42, 13],
+          commitrefs=['rev-1', 'rev-2'],
+          expected_numbers=['42', '13'],
+      ),
+      api.post_check(post_process.StatusSuccess),
+      api.post_process(post_process.DropExpectation),
+  )