feat(storage): add object contexts in Python GCS SDK

packages/google-cloud-storage/google/cloud/storage/_grpc_conversions.py

@@ -87,4 +87,14 @@ def blob_to_proto(blob):
             retain_until_time=retain_until_time_proto,
         )
 
+    contexts = getattr(blob, "contexts", None)
+    if contexts:
+        custom_contexts = {}
+        for key, payload in contexts.custom.items():
+            custom_contexts[key] = _storage_v2.ObjectCustomContextPayload(
+                value=payload.value
+            )
+
+        resource_params["contexts"] = _storage_v2.ObjectContexts(custom=custom_contexts)
+
     return _storage_v2.Object(**resource_params)

packages/google-cloud-storage/google/cloud/storage/blob.py

@@ -105,6 +105,7 @@
     "name",
     "retention",
     "storageClass",
+    "contexts",
 )
 _READ_LESS_THAN_SIZE = (
     "Size {:d} was specified but the file-like object only had {:d} bytes remaining."
@@ -3849,6 +3850,7 @@ def compose(
         if_metageneration_match=None,
         if_source_generation_match=None,
         retry=DEFAULT_RETRY_IF_GENERATION_SPECIFIED,
+        destination_contexts=None,
         delete_source_objects=None,
     ):
         """Concatenate source blobs into this one.
@@ -3910,6 +3912,11 @@ def compose(
             to enable retries regardless of generation precondition setting.
             See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
 
+        :type destination_contexts: :class:`~google.cloud.storage.blob.ObjectContexts`
+        :param destination_contexts:
+            (Optional) New contexts to set for the destination object.
+            See: https://docs.cloud.google.com/storage/docs/use-object-contexts#manage_object_contexts_during_object_operations
+
         :type delete_source_objects: bool
         :param delete_source_objects:
             (Optional) If True, the source objects will be deleted after a
@@ -3965,6 +3972,14 @@ def compose(
 
                 source_objects.append(source_object)
 
+            if destination_contexts is not None:
+                if isinstance(destination_contexts, ObjectContexts):
+                    self.contexts = destination_contexts
+                else:
+                    raise ValueError(
+                        "destination_contexts must be an ObjectContexts object"
+                    )
+
             request = {
                 "sourceObjects": source_objects,
                 "destination": self._properties.copy(),
@@ -4007,6 +4022,7 @@ def rewrite(
         if_source_metageneration_not_match=None,
         timeout=_DEFAULT_TIMEOUT,
         retry=DEFAULT_RETRY_IF_GENERATION_SPECIFIED,
+        destination_contexts=None,
     ):
         """Rewrite source blob into this one.
 
@@ -4090,6 +4106,11 @@ def rewrite(
             to enable retries regardless of generation precondition setting.
             See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
 
+        :type destination_contexts: :class:`~google.cloud.storage.blob.ObjectContexts` or dict
+        :param destination_contexts:
+            (Optional) New contexts to set for the destination object.
+            See: https://docs.cloud.google.com/storage/docs/use-object-contexts#manage_object_contexts_during_object_operations
+
         :rtype: tuple
         :returns: ``(token, bytes_rewritten, total_bytes)``, where ``token``
                   is a rewrite token (``None`` if the rewrite is complete),
@@ -4135,6 +4156,14 @@ def rewrite(
                 if_source_metageneration_not_match=if_source_metageneration_not_match,
             )
 
+            if destination_contexts is not None:
+                if isinstance(destination_contexts, ObjectContexts):
+                    self.contexts = destination_contexts
+                else:
+                    raise ValueError(
+                        "destination_contexts must be an ObjectContexts object"
+                    )
+
             path = f"{source.path}/rewriteTo{self.path}"
             api_response = client._post_resource(
                 path,
@@ -5017,6 +5046,29 @@ def retention(self):
         info = self._properties.get("retention", {})
         return Retention.from_api_repr(info, self)
 
+    @property
+    def contexts(self):
+        """Retrieve the contexts for this object.
+
+        :rtype: :class:`ObjectContexts`
+        :returns: an instance for managing the object's contexts.
+        """
+        info = self._properties.get("contexts", {})
+        return ObjectContexts.from_api_repr(info, self)
+
+    @contexts.setter
+    def contexts(self, value):
+        """Update the contexts for this object.
+
+        :type value: :class:`ObjectContexts` or dict or None
+        :param value: the new contexts for the object.
+        """
+        if value is None:
+            self._properties["contexts"] = None
+        else:
+            self._properties["contexts"] = value
+        self._patch_property("contexts", value)
+
     @property
     def soft_delete_time(self):
         """If this object has been soft-deleted, returns the time at which it became soft-deleted.
@@ -5309,3 +5361,145 @@ def retention_expiration_time(self):
         retention_expiration_time = self.get("retentionExpirationTime")
         if retention_expiration_time is not None:
             return _rfc3339_nanos_to_datetime(retention_expiration_time)
+
+
+class ObjectCustomContextPayload(dict):
+    """Payload for a custom context.
+
+    :type value: str or ``NoneType``
+    :param value: (Optional) The value of the custom context.
+
+    :type create_time: :class:`datetime.datetime` or ``NoneType``
+    :param create_time: (Optional) Creation time of the custom context.
+
+    :type update_time: :class:`datetime.datetime` or ``NoneType``
+    :param update_time: (Optional) Last update time of the custom context.
+    """
+
+    def __init__(self, value=None, create_time=None, update_time=None):
+        data = {"value": value}
+        if create_time is not None:
+            data["createTime"] = _datetime_to_rfc3339(create_time)
+        if update_time is not None:
+            data["updateTime"] = _datetime_to_rfc3339(update_time)
+        super(ObjectCustomContextPayload, self).__init__(data)
+        self._contexts = None
+
+    @property
+    def value(self):
+        """The value of the custom context.
+
+        :rtype: str or ``NoneType``
+        :returns: The value of the custom context.
+        """
+        return self.get("value")
+
+    @value.setter
+    def value(self, value):
+        self["value"] = value
+        if hasattr(self, "_contexts") and self._contexts and self._contexts.blob:
+            self._contexts.blob._patch_property("contexts", self._contexts)
+
+    @property
+    def create_time(self):
+        """Creation time of the custom context.
+
+        :rtype: :class:`datetime.datetime` or ``NoneType``
+        :returns: Datetime object parsed from RFC3339 valid timestamp.
+        """
+        create_time = self.get("createTime")
+        if create_time is not None:
+            return _rfc3339_nanos_to_datetime(create_time)
+
+    @property
+    def update_time(self):
+        """Last update time of the custom context.
+
+        :rtype: :class:`datetime.datetime` or ``NoneType``
+        :returns: Datetime object parsed from RFC3339 valid timestamp.
+        """
+        update_time = self.get("updateTime")
+        if update_time is not None:
+            return _rfc3339_nanos_to_datetime(update_time)
+
+
+class ObjectContexts(dict):
+    """Container for an object's contexts.
+
+    :type blob: :class:`Blob`
+    :param blob: blob for which these contexts apply to.
+
+    :type custom: dict or ``NoneType``
+    :param custom: (Optional) Custom contexts mapping.
+    """
+
+    def __init__(self, blob, custom=None):
+        data = {}
+        if custom is not None:
+            if not isinstance(custom, dict):
+                raise ValueError(
+                    "custom must be a dictionary mapping keys to ObjectCustomContextPayload instances"
+                )
+            for payload in custom.values():
+                if not isinstance(payload, ObjectCustomContextPayload):
+                    raise ValueError(
+                        "All values in custom must be ObjectCustomContextPayload instances"
+                    )
+            data["custom"] = custom
+        super(ObjectContexts, self).__init__(data)
+        self._blob = blob
+        if custom is not None:
+            for payload in custom.values():
+                payload._contexts = self
+
+    @classmethod
+    def from_api_repr(cls, resource, blob):
+        """Factory: construct instance from resource.
+
+        :type resource: dict
+        :param resource: mapping as returned from API call.
+
+        :type blob: :class:`Blob`
+        :param blob: Blob for which these contexts apply to.
+
+        :rtype: :class:`ObjectContexts`
+        :returns: ObjectContexts instance created from resource.
+        """
+        instance = cls(blob)
+        custom = {}
+        for key, payload_resource in resource.get("custom", {}).items():
+            payload = ObjectCustomContextPayload()
+            payload.update(payload_resource)
+            payload._contexts = instance
+            custom[key] = payload
+        instance["custom"] = custom
+        return instance
+
+    @property
+    def blob(self):
+        """Blob for which these contexts apply to.
+
+        :rtype: :class:`Blob`
+        :returns: the instance's blob.
+        """
+        return self._blob
+
+    @property
+    def custom(self):
+        """Custom contexts mapping.
+
+        :rtype: dict
+        :returns: Mapping of keys to :class:`ObjectCustomContextPayload` instances.
+        """
+        if "custom" not in self:
+            self["custom"] = {}
+        return self["custom"]
+
+    @custom.setter
+    def custom(self, value):
+        if not isinstance(value, dict):
+            raise ValueError(
+                "custom must be a dictionary mapping keys to ObjectCustomContextPayload instances"
+            )
+        self["custom"] = value
+        self.blob._patch_property("contexts", self)

packages/google-cloud-storage/google/cloud/storage/bucket.py

@@ -42,6 +42,7 @@
 from google.cloud.storage._signing import generate_signed_url_v2, generate_signed_url_v4
 from google.cloud.storage.acl import BucketACL, DefaultObjectACL
 from google.cloud.storage.blob import Blob, _quote
+from google.cloud.storage.blob import ObjectContexts
 from google.cloud.storage.constants import (
     _DEFAULT_TIMEOUT,
     ARCHIVE_STORAGE_CLASS,
@@ -1423,6 +1424,7 @@ def list_blobs(
         include_folders_as_prefixes=None,
         soft_deleted=None,
         page_size=None,
+        filter_=None,
     ):
         """Return an iterator used to find blobs in the bucket.
 
@@ -1516,6 +1518,11 @@ def list_blobs(
             Note ``soft_deleted`` and ``versions`` cannot be set to True simultaneously. See:
             https://cloud.google.com/storage/docs/soft-delete
 
+        :type filter_: str
+        :param filter_:
+            (Optional) Filter string used to filter objects. See:
+            https://docs.cloud.google.com/storage/docs/listing-objects#filter-by-object-contexts-syntax
+
         :type page_size: int
         :param page_size:
             (Optional) Maximum number of blobs to return in each page.
@@ -1545,6 +1552,7 @@ def list_blobs(
                 match_glob=match_glob,
                 include_folders_as_prefixes=include_folders_as_prefixes,
                 soft_deleted=soft_deleted,
+                filter_=filter_,
             )
 
     def list_notifications(
@@ -1972,6 +1980,7 @@ def copy_blob(
         if_source_metageneration_not_match=None,
         timeout=_DEFAULT_TIMEOUT,
         retry=DEFAULT_RETRY_IF_GENERATION_SPECIFIED,
+        destination_contexts=None,
     ):
         """Copy the given blob to the given bucket, optionally with a new name.
 
@@ -2065,6 +2074,10 @@ def copy_blob(
             to enable retries regardless of generation precondition setting.
             See [Configuring Retries](https://cloud.google.com/python/docs/reference/storage/latest/retry_timeout).
 
+        :type destination_contexts: :class:`~google.cloud.storage.blob.ObjectContexts` or dict
+        :param destination_contexts:
+            (Optional) New contexts to set for the destination object.
+            See: https://docs.cloud.google.com/storage/docs/use-object-contexts#manage_object_contexts_during_object_operations
         :rtype: :class:`google.cloud.storage.blob.Blob`
         :returns: The new Blob.
         """
@@ -2094,10 +2107,22 @@ def copy_blob(
                 new_name = blob.name
 
             new_blob = Blob(bucket=destination_bucket, name=new_name)
+
+            if destination_contexts is not None:
+                if isinstance(destination_contexts, ObjectContexts):
+                    new_blob.contexts = destination_contexts
+                else:
+                    raise ValueError(
+                        "destination_contexts must be an ObjectContexts object"
+                    )
+                request_body = new_blob._properties.copy()
+            else:
+                request_body = None
+
             api_path = blob.path + "/copyTo" + new_blob.path
             copy_result = client._post_resource(
                 api_path,
-                None,
+                request_body,
                 query_params=query_params,
                 timeout=timeout,
                 retry=retry,

packages/google-cloud-storage/google/cloud/storage/client.py

@@ -1291,6 +1291,7 @@ def list_blobs(
         match_glob=None,
         include_folders_as_prefixes=None,
         soft_deleted=None,
+        filter_=None,
     ):
         """Return an iterator used to find blobs in the bucket.
 
@@ -1400,6 +1401,10 @@ def list_blobs(
                 Note ``soft_deleted`` and ``versions`` cannot be set to True simultaneously. See:
                 https://cloud.google.com/storage/docs/soft-delete
 
+            filter_ (str):
+                (Optional) Filter string used to filter objects. See:
+                https://docs.cloud.google.com/storage/docs/listing-objects#filter-by-object-contexts-syntax
+
         Returns:
             Iterator of all :class:`~google.cloud.storage.blob.Blob`
             in this bucket matching the arguments. The RPC call
@@ -1443,6 +1448,9 @@ def list_blobs(
             if soft_deleted is not None:
                 extra_params["softDeleted"] = soft_deleted
 
+            if filter_ is not None:
+                extra_params["filter"] = filter_
+
             if bucket.user_project is not None:
                 extra_params["userProject"] = bucket.user_project