feat: add *generation*match args into Blob.compose()

google/cloud/storage/blob.py

@@ -2234,34 +2234,104 @@ def make_private(self, client=None):
  self.acl.all().revoke_read()
  self.acl.save(client=client)
 
- def compose(self, sources, client=None, timeout=_DEFAULT_TIMEOUT):
+ def compose(
+ self,
+ sources,
+ client=None,
+ timeout=_DEFAULT_TIMEOUT,
+ if_generation_match=None,
+ if_metageneration_match=None,
+ ):
  """Concatenate source blobs into this one.
 
  If :attr:`user_project` is set on the bucket, bills the API request
  to that project.
 
  :type sources: list of :class:`Blob`
- :param sources: blobs whose contents will be composed into this blob.
+ :param sources: Blobs whose contents will be composed into this blob.
 
  :type client: :class:`~google.cloud.storage.client.Client` or
  ``NoneType``
- :param client: (Optional) The client to use. If not passed, falls back
+ :param client: (Optional) The client to use. If not passed, falls back
  to the ``client`` stored on the blob's bucket.
+
  :type timeout: float or tuple
  :param timeout: (Optional) The amount of time, in seconds, to wait
  for the server response.
 
  Can also be passed as a tuple (connect_timeout, read_timeout).
  See :meth:`requests.Session.request` documentation for details.
+
+ :type if_generation_match: list of long
+ :param if_generation_match: (Optional) Make the operation conditional on whether
+ the blob's current generation matches the given value.
+ Setting to 0 makes the operation succeed only if there
+ are no live versions of the blob. The list must match
+ ``sources`` item-to-item.
+
+ :type if_metageneration_match: list of long
+ :param if_metageneration_match: (Optional) Make the operation conditional on whether
+ the blob's current metageneration matches the given
+ value. The list must match ``sources`` item-to-item.
+
+ Example:
+ Compose blobs using generation match preconditions.
+
+ >>> from google.cloud import storage
+ >>> client = storage.Client()
+ >>> bucket = client.bucket("bucket-name")
+
+ >>> blobs = [bucket.blob("blob-name-1"), bucket.blob("blob-name-2")]
+ >>> if_generation_match = [None] * len(blobs)
+ >>> if_generation_match[0] = "123" # precondition for "blob-name-1"
+
+ >>> composed_blob = bucket.blob("composed-name")
+ >>> composed_blob.compose(blobs, if_generation_match)
  """
+ sources_len = len(sources)
+ if if_generation_match is not None and len(if_generation_match) != sources_len:
+ raise ValueError(
+ "'if_generation_match' length must be the same as 'sources' length"
+ )
+
+ if (
+ if_metageneration_match is not None
+ and len(if_metageneration_match) != sources_len
+ ):
+ raise ValueError(
+ "'if_metageneration_match' length must be the same as 'sources' length"
+ )
+
  client = self._require_client(client)
  query_params = {}
 
  if self.user_project is not None:
  query_params["userProject"] = self.user_project
 
+ source_objects = []
+ for index, source in enumerate(sources):
+ source_object = {"name": source.name}
+
+ preconditions = {}
+ if (
+ if_generation_match is not None
+ and if_generation_match[index] is not None
+ ):
+ preconditions["ifGenerationMatch"] = if_generation_match[index]
+
+ if (
+ if_metageneration_match is not None
+ and if_metageneration_match[index] is not None
+ ):
+ preconditions["ifMetagenerationMatch"] = if_metageneration_match[index]
+
+ if preconditions:
+ source_object["objectPreconditions"] = preconditions
+
+ source_objects.append(source_object)
+
  request = {
- "sourceObjects": [{"name": source.name} for source in sources],
+ "sourceObjects": source_objects,
  "destination": self._properties.copy(),
  }
  api_response = client._connection.api_request(

tests/system/test_system.py

@@ -1441,6 +1441,34 @@ def test_compose_replace_existing_blob(self):
  composed = original.download_as_string()
  self.assertEqual(composed, BEFORE + TO_APPEND)
 
+ def test_compose_with_generation_match(self):
+ BEFORE = b"AAA\n"
+ original = self.bucket.blob("original")
+ original.content_type = "text/plain"
+ original.upload_from_string(BEFORE)
+ self.case_blobs_to_delete.append(original)
+
+ TO_APPEND = b"BBB\n"
+ to_append = self.bucket.blob("to_append")
+ to_append.upload_from_string(TO_APPEND)
+ self.case_blobs_to_delete.append(to_append)
+
+ with self.assertRaises(google.api_core.exceptions.PreconditionFailed):
+ original.compose(
+ [original, to_append],
+ if_generation_match=[6, 7],
+ if_metageneration_match=[8, 9],
+ )
+
+ original.compose(
+ [original, to_append],
+ if_generation_match=[original.generation, to_append.generation],
+ if_metageneration_match=[original.metageneration, to_append.metageneration],
+ )
+
+ composed = original.download_as_string()
+ self.assertEqual(composed, BEFORE + TO_APPEND)
+
  @unittest.skipUnless(USER_PROJECT, "USER_PROJECT not set in environment.")
  def test_compose_with_user_project(self):
  new_bucket_name = "compose-user-project" + unique_resource_id("-")

tests/unit/test_blob.py

@@ -2676,7 +2676,7 @@ def test_make_private(self):
  def test_compose_wo_content_type_set(self):
  SOURCE_1 = "source-1"
  SOURCE_2 = "source-2"
- DESTINATION = "destinaton"
+ DESTINATION = "destination"
  RESOURCE = {}
  after = ({"status": http_client.OK}, RESOURCE)
  connection = _Connection(after)
@@ -2711,7 +2711,7 @@ def test_compose_wo_content_type_set(self):
  def test_compose_minimal_w_user_project(self):
  SOURCE_1 = "source-1"
  SOURCE_2 = "source-2"
- DESTINATION = "destinaton"
+ DESTINATION = "destination"
  RESOURCE = {"etag": "DEADBEEF"}
  USER_PROJECT = "user-project-123"
  after = ({"status": http_client.OK}, RESOURCE)
@@ -2747,7 +2747,7 @@ def test_compose_minimal_w_user_project(self):
  def test_compose_w_additional_property_changes(self):
  SOURCE_1 = "source-1"
  SOURCE_2 = "source-2"
- DESTINATION = "destinaton"
+ DESTINATION = "destination"
  RESOURCE = {"etag": "DEADBEEF"}
  after = ({"status": http_client.OK}, RESOURCE)
  connection = _Connection(after)
@@ -2785,6 +2785,129 @@ def test_compose_w_additional_property_changes(self):
  },
  )
 
+ def test_compose_w_generation_match(self):
+ SOURCE_1 = "source-1"
+ SOURCE_2 = "source-2"
+ DESTINATION = "destination"
+ RESOURCE = {}
+ GENERATION_NUMBERS = [6, 9]
+ METAGENERATION_NUMBERS = [7, 1]
+
+ after = ({"status": http_client.OK}, RESOURCE)
+ connection = _Connection(after)
+ client = _Client(connection)
+ bucket = _Bucket(client=client)
+ source_1 = self._make_one(SOURCE_1, bucket=bucket)
+ source_2 = self._make_one(SOURCE_2, bucket=bucket)
+
+ destination = self._make_one(DESTINATION, bucket=bucket)
+ destination.compose(
+ sources=[source_1, source_2],
+ if_generation_match=GENERATION_NUMBERS,
+ if_metageneration_match=METAGENERATION_NUMBERS,
+ )
+
+ kw = connection._requested
+ self.assertEqual(len(kw), 1)
+ self.assertEqual(
+ kw[0],
+ {
+ "method": "POST",
+ "path": "/b/name/o/%s/compose" % DESTINATION,
+ "query_params": {},
+ "data": {
+ "sourceObjects": [
+ {
+ "name": source_1.name,
+ "objectPreconditions": {
+ "ifGenerationMatch": GENERATION_NUMBERS[0],
+ "ifMetagenerationMatch": METAGENERATION_NUMBERS[0],
+ },
+ },
+ {
+ "name": source_2.name,
+ "objectPreconditions": {
+ "ifGenerationMatch": GENERATION_NUMBERS[1],
+ "ifMetagenerationMatch": METAGENERATION_NUMBERS[1],
+ },
+ },
+ ],
+ "destination": {},
+ },
+ "_target_object": destination,
+ "timeout": self._get_default_timeout(),
+ },
+ )
+
+ def test_compose_w_generation_match_bad_length(self):
+ SOURCE_1 = "source-1"
+ SOURCE_2 = "source-2"
+ DESTINATION = "destination"
+ GENERATION_NUMBERS = [6]
+ METAGENERATION_NUMBERS = [7]
+
+ after = ({"status": http_client.OK}, {})
+ connection = _Connection(after)
+ client = _Client(connection)
+ bucket = _Bucket(client=client)
+ source_1 = self._make_one(SOURCE_1, bucket=bucket)
+ source_2 = self._make_one(SOURCE_2, bucket=bucket)
+
+ destination = self._make_one(DESTINATION, bucket=bucket)
+
+ with self.assertRaises(ValueError):
+ destination.compose(
+ sources=[source_1, source_2], if_generation_match=GENERATION_NUMBERS,
+ )
+ with self.assertRaises(ValueError):
+ destination.compose(
+ sources=[source_1, source_2],
+ if_metageneration_match=METAGENERATION_NUMBERS,
+ )
+
+ def test_compose_w_generation_match_nones(self):
+ SOURCE_1 = "source-1"
+ SOURCE_2 = "source-2"
+ DESTINATION = "destination"
+ GENERATION_NUMBERS = [6, None]
+
+ after = ({"status": http_client.OK}, {})
+ connection = _Connection(after)
+ client = _Client(connection)
+ bucket = _Bucket(client=client)
+ source_1 = self._make_one(SOURCE_1, bucket=bucket)
+ source_2 = self._make_one(SOURCE_2, bucket=bucket)
+
+ destination = self._make_one(DESTINATION, bucket=bucket)
+ destination.compose(
+ sources=[source_1, source_2], if_generation_match=GENERATION_NUMBERS,
+ )
+
+ kw = connection._requested
+ self.assertEqual(len(kw), 1)
+ self.assertEqual(
+ kw[0],
+ {
+ "method": "POST",
+ "path": "/b/name/o/%s/compose" % DESTINATION,
+ "query_params": {},
+ "data": {
+ "sourceObjects": [
+ {
+ "name": source_1.name,
+ "objectPreconditions": {
+ "ifGenerationMatch": GENERATION_NUMBERS[0],
+ },
+ },
+ {"name": source_2.name},
+ ],
+ "destination": {},
+ },
+ "_target_object": destination,
+ "timeout": self._get_default_timeout(),
+ },
+ )
+
  def test_rewrite_response_without_resource(self):
  SOURCE_BLOB = "source"
  DEST_BLOB = "dest"