kernelci.cli: add pagination options and helper

Add the --page-length / -l and --page-number / -n options for
paginated API data.  Provide a kernelci.cli.get_pagination() function
to convert these arguments into the offset / limit values used with
the API as pagination is easier with relative numbers on the command
line.  Add unit tests accordingly to test this function.

Signed-off-by: Guillaume Tucker <[email protected]>

Author: gctucker

kernelci/cli/__init__.py

@@ -35,6 +35,14 @@ class Args:  # pylint: disable=too-few-public-methods
         '--indent', type=int,
         help="Intentation level for structured data output"
     )
+    page_length = click.option(
+        '-l', '--page-length', type=int,
+        help="Page length in paginated data"
+    )
+    page_number = click.option(
+        '-n', '--page-number', type=int,
+        help="Page number in paginated data"
+    )
     settings = click.option(
         '-s', '--toml-settings', 'settings',
         help="Path to the TOML user settings"
@@ -190,3 +198,26 @@ def split_attributes(attributes: typing.List[str]):
         ''.join((key, opstr)): value
         for key, (opstr, value) in parsed.items()
     }
+
+
+def get_pagination(page_length: int, page_number: int):
+    """Get the offset and limit values for paginated data
+
+    Return a 2-tuple (offset, limit) which can be used with paginated data from
+    the API.  The `page_length` and `page_number` values are used to get the
+    absolute start `offset`.  The `page_length` value is the same as the
+    `limit` API value, essentially the maximum number of items per page.
+    """
+    if page_length is None:
+        page_length = 10
+    elif page_length < 1:
+        raise click.UsageError(
+            f"Page length must be at least 1, got {page_length}"
+        )
+    if page_number is None:
+        page_number = 0
+    elif page_number < 0:
+        raise click.UsageError(
+            f"Page number must be at least 0, got {page_number}"
+        )
+    return page_number * page_length, page_length

tests/test_cli.py

@@ -113,3 +113,36 @@ def test_split_invalid_attributes():
     for attrs in attributes:
         with pytest.raises(click.ClickException):
             kernelci.cli.split_attributes(attrs)
+
+
+def test_pagination():
+    """Test the logic to get pagination values"""
+    values = {
+        (None, None): (0, 10),
+        (1, 0): (0, 1),
+        (1, 1): (1, 1),
+        (12, 345): (12 * 345, 12),
+        (12345, 3): (3 * 12345, 12345),
+        (4567, 0): (0, 4567),
+    }
+    for (p_len, p_num), (offset, limit) in values.items():
+        result = kernelci.cli.get_pagination(p_len, p_num)
+        assert result == (offset, limit)
+
+
+def test_invalid_pagination():
+    """Test that errors are reported with invalid pagination values"""
+    values = [
+        (0, 1),
+        (0.1, 1),
+        (-1, 0),
+        (0, 0),
+        (0, -1),
+        (1, -1),
+        (-123, -123),
+        (123, -1),
+        (0, 123),
+    ]
+    for p_len, p_num in values:
+        with pytest.raises(click.UsageError):
+            kernelci.cli.get_pagination(p_len, p_num)