feat: add matchGlob parameter to list_blobs (#1055)

* feat: add matchGlob parameter to list_blobs

* update docstrings and tests

* move parameter order

* align param order

Author: cojenco

google/cloud/storage/bucket.py

@@ -1290,6 +1290,7 @@ def list_blobs(
         client=None,
         timeout=_DEFAULT_TIMEOUT,
         retry=DEFAULT_RETRY,
+        match_glob=None,
     ):
         """Return an iterator used to find blobs in the bucket.
 
@@ -1365,6 +1366,12 @@ def list_blobs(
         :param retry:
             (Optional) How to retry the RPC. See: :ref:`configuring_retries`
 
+        :type match_glob: str
+        :param match_glob:
+            (Optional) A glob pattern used to filter results (for example, foo*bar).
+            The string value must be UTF-8 encoded. See:
+            https://cloud.google.com/storage/docs/json_api/v1/objects/list#list-object-glob
+
         :rtype: :class:`~google.api_core.page_iterator.Iterator`
         :returns: Iterator of all :class:`~google.cloud.storage.blob.Blob`
                   in this bucket matching the arguments.
@@ -1384,6 +1391,7 @@ def list_blobs(
             fields=fields,
             timeout=timeout,
             retry=retry,
+            match_glob=match_glob,
         )
 
     def list_notifications(

google/cloud/storage/client.py

@@ -1127,6 +1127,7 @@ def list_blobs(
         page_size=None,
         timeout=_DEFAULT_TIMEOUT,
         retry=DEFAULT_RETRY,
+        match_glob=None,
     ):
         """Return an iterator used to find blobs in the bucket.
 
@@ -1220,6 +1221,11 @@ def list_blobs(
                 See the retry.py source code and docstrings in this package (google.cloud.storage.retry) for
                 information on retry types and how to configure them.
 
+            match_glob (str):
+                (Optional) A glob pattern used to filter results (for example, foo*bar).
+                The string value must be UTF-8 encoded. See:
+                https://cloud.google.com/storage/docs/json_api/v1/objects/list#list-object-glob
+
         Returns:
             Iterator of all :class:`~google.cloud.storage.blob.Blob`
             in this bucket matching the arguments. The RPC call
@@ -1238,6 +1244,9 @@ def list_blobs(
         if delimiter is not None:
             extra_params["delimiter"] = delimiter
 
+        if match_glob is not None:
+            extra_params["matchGlob"] = match_glob
+
         if start_offset is not None:
             extra_params["startOffset"] = start_offset
 

tests/system/test_bucket.py

@@ -621,6 +621,38 @@ def test_bucket_list_blobs_hierarchy_w_include_trailing_delimiter(
     assert iterator.prefixes == expected_prefixes
 
 
+@_helpers.retry_failures
+def test_bucket_list_blobs_w_match_glob(
+    storage_client,
+    buckets_to_delete,
+    blobs_to_delete,
+):
+    bucket_name = _helpers.unique_name("w-matchglob")
+    bucket = _helpers.retry_429_503(storage_client.create_bucket)(bucket_name)
+    buckets_to_delete.append(bucket)
+
+    payload = b"helloworld"
+    blob_names = ["foo/bar", "foo/baz", "foo/foobar", "foobar"]
+    for name in blob_names:
+        blob = bucket.blob(name)
+        blob.upload_from_string(payload)
+        blobs_to_delete.append(blob)
+
+    match_glob_results = {
+        "foo*bar": ["foobar"],
+        "foo**bar": ["foo/bar", "foo/foobar", "foobar"],
+        "**/foobar": ["foo/foobar", "foobar"],
+        "*/ba[rz]": ["foo/bar", "foo/baz"],
+        "*/ba[!a-y]": ["foo/baz"],
+        "**/{foobar,baz}": ["foo/baz", "foo/foobar", "foobar"],
+        "foo/{foo*,*baz}": ["foo/baz", "foo/foobar"],
+    }
+    for match_glob, expected_names in match_glob_results.items():
+        blob_iter = bucket.list_blobs(match_glob=match_glob)
+        blobs = list(blob_iter)
+        assert [blob.name for blob in blobs] == expected_names
+
+
 def test_bucket_w_retention_period(
     storage_client,
     buckets_to_delete,

tests/unit/test_bucket.py

@@ -1143,6 +1143,7 @@ def test_list_blobs_w_defaults(self):
         expected_max_results = None
         expected_prefix = None
         expected_delimiter = None
+        expected_match_glob = None
         expected_start_offset = None
         expected_end_offset = None
         expected_include_trailing_delimiter = None
@@ -1163,6 +1164,7 @@ def test_list_blobs_w_defaults(self):
             fields=expected_fields,
             timeout=self._get_default_timeout(),
             retry=DEFAULT_RETRY,
+            match_glob=expected_match_glob,
         )
 
     def test_list_blobs_w_explicit(self):
@@ -1171,6 +1173,7 @@ def test_list_blobs_w_explicit(self):
         page_token = "ABCD"
         prefix = "subfolder"
         delimiter = "/"
+        match_glob = "**txt"
         start_offset = "c"
         end_offset = "g"
         include_trailing_delimiter = True
@@ -1197,6 +1200,7 @@ def test_list_blobs_w_explicit(self):
             client=other_client,
             timeout=timeout,
             retry=retry,
+            match_glob=match_glob,
         )
 
         self.assertIs(iterator, other_client.list_blobs.return_value)
@@ -1205,6 +1209,7 @@ def test_list_blobs_w_explicit(self):
         expected_max_results = max_results
         expected_prefix = prefix
         expected_delimiter = delimiter
+        expected_match_glob = match_glob
         expected_start_offset = start_offset
         expected_end_offset = end_offset
         expected_include_trailing_delimiter = include_trailing_delimiter
@@ -1225,6 +1230,7 @@ def test_list_blobs_w_explicit(self):
             fields=expected_fields,
             timeout=timeout,
             retry=retry,
+            match_glob=expected_match_glob,
         )
 
     def test_list_notifications_w_defaults(self):

tests/unit/test_client.py

@@ -1928,6 +1928,7 @@ def test_list_blobs_w_explicit_w_user_project(self):
         page_token = "ABCD"
         prefix = "subfolder"
         delimiter = "/"
+        match_glob = "**txt"
         start_offset = "c"
         end_offset = "g"
         include_trailing_delimiter = True
@@ -1962,6 +1963,7 @@ def test_list_blobs_w_explicit_w_user_project(self):
             page_size=page_size,
             timeout=timeout,
             retry=retry,
+            match_glob=match_glob,
         )
 
         self.assertIs(iterator, client._list_resource.return_value)
@@ -1976,6 +1978,7 @@ def test_list_blobs_w_explicit_w_user_project(self):
             "projection": projection,
             "prefix": prefix,
             "delimiter": delimiter,
+            "matchGlob": match_glob,
             "startOffset": start_offset,
             "endOffset": end_offset,
             "includeTrailingDelimiter": include_trailing_delimiter,