pixeltable 0.3.14__py3-none-any.whl → 0.5.7__py3-none-any.whl

pixeltable/utils/exception_handler.py

@@ -1,35 +1,12 @@
 import logging
-import sys
-from typing import Any, Callable, Optional, TypeVar
+from typing import Any, Callable, TypeVar
 
 R = TypeVar('R')
 
-
-def _is_in_exception() -> bool:
-    """
-    Check if code is currently executing within an exception context.
-    """
-    current_exception = sys.exc_info()[1]
-    return current_exception is not None
-
-
-def run_cleanup_on_exception(cleanup_func: Callable[..., R], *args: Any, **kwargs: Any) -> Optional[R]:
-    """
-    Runs cleanup only when running in exception context.
-
-    The function `run_cleanup_on_exception()` should be used to clean up resources when an operation fails.
-    This is typically done using a try, except, and finally block, with the resource cleanup logic placed within
-    the except block. However, this pattern may not handle KeyboardInterrupt exceptions.
-    To ensure that resources are always cleaned up at least once when an exception or KeyboardInterrupt occurs,
-    create an idempotent function for cleaning up resources and pass it to the `run_cleanup_on_exception()` function
-    from the finally block.
-    """
-    if _is_in_exception():
-        return run_cleanup(cleanup_func, *args, raise_error=False, **kwargs)
-    return None
+logger = logging.getLogger('pixeltable')
 
 
-def run_cleanup(cleanup_func: Callable[..., R], *args: Any, raise_error: bool = True, **kwargs: Any) -> Optional[R]:
+def run_cleanup(cleanup_func: Callable[..., R], *args: Any, raise_error: bool = True, **kwargs: Any) -> R | None:
     """
     Runs a cleanup function. If interrupted, retry cleanup.
     The `run_cleanup()` function ensures that the `cleanup_func()` function executes at least once.
@@ -40,20 +17,20 @@ def run_cleanup(cleanup_func: Callable[..., R], *args: Any, raise_error: bool =
         raise_error: raise an exception if an error occurs during cleanup.
     """
     try:
-        logging.debug(f'Running cleanup function: {cleanup_func.__name__!r}')
+        logger.debug(f'Running cleanup function: {cleanup_func.__name__!r}')
         return cleanup_func(*args, **kwargs)
     except KeyboardInterrupt as interrupt:
         # Save original exception and re-attempt cleanup
         original_exception = interrupt
-        logging.debug(f'Cleanup {cleanup_func.__name__!r} interrupted, retrying')
+        logger.debug(f'Cleanup {cleanup_func.__name__!r} interrupted, retrying')
         try:
             return cleanup_func(*args, **kwargs)
         except Exception as e:
             # Suppress this exception
-            logging.error(f'Cleanup {cleanup_func.__name__!r} failed with exception {e}')
+            logger.error(f'Cleanup {cleanup_func.__name__!r} failed with exception {e.__class__}: {e}')
         raise KeyboardInterrupt from original_exception
     except Exception as e:
-        logging.error(f'Cleanup {cleanup_func.__name__!r} failed with exception {e}')
+        logger.error(f'Cleanup {cleanup_func.__name__!r} failed with exception {e.__class__}: {e}')
         if raise_error:
             raise e
     return None

pixeltable/utils/filecache.py

@@ -9,7 +9,7 @@ from collections import OrderedDict, defaultdict
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import NamedTuple, Optional
+from typing import NamedTuple
 from uuid import UUID
 
 import pixeltable.exceptions as excs
@@ -58,7 +58,7 @@ class FileCache:
     - implement MRU eviction for queries that exceed the capacity
     """
 
-    __instance: Optional[FileCache] = None
+    __instance: FileCache | None = None
 
     cache: OrderedDict[str, CacheEntry]
     total_size: int
@@ -126,12 +126,12 @@ class FileCache:
             return 0
         return int(self.total_size / len(self.cache))
 
-    def num_files(self, tbl_id: Optional[UUID] = None) -> int:
+    def num_files(self, tbl_id: UUID | None = None) -> int:
         if tbl_id is None:
             return len(self.cache)
         return sum(e.tbl_id == tbl_id for e in self.cache.values())
 
-    def clear(self, tbl_id: Optional[UUID] = None) -> None:
+    def clear(self, tbl_id: UUID | None = None) -> None:
         """
         For testing purposes: allow resetting capacity and stats.
         """
@@ -174,7 +174,7 @@ class FileCache:
         h.update(url.encode())
         return h.hexdigest()
 
-    def lookup(self, url: str) -> Optional[Path]:
+    def lookup(self, url: str) -> Path | None:
         self.num_requests += 1
         key = self._url_hash(url)
         entry = self.cache.get(key, None)
@@ -214,7 +214,7 @@ class FileCache:
         new_path = entry.path
         os.rename(str(path), str(new_path))
         new_path.touch(exist_ok=True)
-        _logger.debug(f'added entry for cell {url} to file cache')
+        _logger.debug(f'FileCache: cached url {url} with file name {new_path}')
         return new_path
 
     def ensure_capacity(self, size: int) -> None:

pixeltable/utils/formatter.py

@@ -4,11 +4,13 @@ import io
 import json
 import logging
 import mimetypes
-from typing import Any, Callable, Optional
+import uuid
+from typing import Any, Callable
 
 import av
 import numpy as np
 from PIL import Image
+from pypdfium2 import PdfDocument  # type: ignore[import-untyped]
 
 import pixeltable.type_system as ts
 from pixeltable.utils.http_server import get_file_uri
@@ -19,11 +21,11 @@ _logger = logging.getLogger('pixeltable')
 class Formatter:
     """
     A factory for constructing HTML formatters for Pixeltable data. The formatters are used to customize
-    the rendering of `DataFrameResultSet`s in notebooks.
+    the rendering of `ResultSet`s in notebooks.
 
     Args:
-        num_rows: Number of rows in the DataFrame being rendered.
-        num_cols: Number of columns in the DataFrame being rendered.
+        num_rows: Number of rows in the `ResultSet` being rendered.
+        num_cols: Number of columns in the `ResultSet` being rendered.
         http_address: Root address of the Pixeltable HTTP server (used to construct URLs for media references).
     """
 
@@ -39,9 +41,13 @@ class Formatter:
         self.__num_cols = num_cols
         self.__http_address = http_address
 
-    def get_pandas_formatter(self, col_type: ts.ColumnType) -> Optional[Callable]:
+    def get_pandas_formatter(self, col_type: ts.ColumnType) -> Callable | None:
         if col_type.is_string_type():
             return self.format_string
+        if col_type.is_uuid_type():
+            return self.format_uuid
+        if col_type.is_binary_type():
+            return self.format_binary
         if col_type.is_float_type():
             return self.format_float
         if col_type.is_json_type():
@@ -63,10 +69,24 @@ class Formatter:
         """
         Escapes special characters in `val`, and abbreviates `val` if its length exceeds `_STRING_MAX_LEN`.
         """
-        return cls.__escape(cls.__abbreviate(val, cls.__STRING_MAX_LEN))
+        return cls.__escape(cls.abbreviate(val))
 
     @classmethod
-    def __abbreviate(cls, val: str, max_len: int) -> str:
+    def format_uuid(cls, val: uuid.UUID | None) -> str:
+        """
+        Formats a UUID by converting it to a string and applying string formatting.
+        """
+        return '' if val is None else cls.format_string(str(val))
+
+    @classmethod
+    def format_binary(cls, val: bytes) -> str:
+        """
+        Formats binary data by converting it to an encoded string and applying string formatting.
+        """
+        return cls.format_string(str(val))
+
+    @classmethod
+    def abbreviate(cls, val: str, max_len: int = __STRING_MAX_LEN) -> str:
         if len(val) > max_len:
             edgeitems = (max_len - len(cls.__STRING_SEP)) // 2
             return f'{val[:edgeitems]}{cls.__STRING_SEP}{val[-edgeitems:]}'
@@ -94,41 +114,45 @@ class Formatter:
         )
 
     @classmethod
-    def format_json(cls, val: Any) -> str:
+    def format_json(cls, val: Any, escape_strings: bool = True) -> str:
         if isinstance(val, str):
             # JSON-like formatting will be applied to strings that appear nested within a list or dict
             # (quote the string; escape any quotes inside the string; shorter abbreviations).
             # However, if the string appears in top-level position (i.e., the entire JSON value is a
             # string), then we format it like an ordinary string.
-            return cls.format_string(val)
+            return cls.format_string(val) if escape_strings else cls.abbreviate(val)
         # In all other cases, dump the JSON struct recursively.
-        return cls.__format_json_rec(val)
+        return cls.__format_json_rec(val, escape_strings)
 
     @classmethod
-    def __format_json_rec(cls, val: Any) -> str:
+    def __format_json_rec(cls, val: Any, escape_strings: bool) -> str:
         if isinstance(val, str):
-            return cls.__escape(json.dumps(cls.__abbreviate(val, cls.__NESTED_STRING_MAX_LEN)))
+            formatted = json.dumps(cls.abbreviate(val, cls.__NESTED_STRING_MAX_LEN))
+            return cls.__escape(formatted) if escape_strings else formatted
         if isinstance(val, float):
             return cls.format_float(val)
         if isinstance(val, np.ndarray):
             return cls.format_array(val)
         if isinstance(val, list):
             if len(val) < cls.__LIST_THRESHOLD:
-                components = [cls.__format_json_rec(x) for x in val]
+                components = [cls.__format_json_rec(x, escape_strings) for x in val]
             else:
-                components = [cls.__format_json_rec(x) for x in val[: cls.__LIST_EDGEITEMS]]
+                components = [cls.__format_json_rec(x, escape_strings) for x in val[: cls.__LIST_EDGEITEMS]]
                 components.append('...')
-                components.extend(cls.__format_json_rec(x) for x in val[-cls.__LIST_EDGEITEMS :])
+                components.extend(cls.__format_json_rec(x, escape_strings) for x in val[-cls.__LIST_EDGEITEMS :])
             return '[' + ', '.join(components) + ']'
         if isinstance(val, dict):
-            kv_pairs = (f'{cls.__format_json_rec(k)}: {cls.__format_json_rec(v)}' for k, v in val.items())
+            kv_pairs = (
+                f'{cls.__format_json_rec(k, escape_strings)}: {cls.__format_json_rec(v, escape_strings)}'
+                for k, v in val.items()
+            )
             return '{' + ', '.join(kv_pairs) + '}'
 
         # Everything else
         try:
             return json.dumps(val)
         except TypeError:  # Not JSON serializable
-            return str(val)
+            return cls.__escape(str(val))
 
     def format_img(self, img: Image.Image) -> str:
         """
@@ -152,22 +176,19 @@ class Formatter:
             """
 
     def format_video(self, file_path: str) -> str:
-        thumb_tag = ''
         # Attempt to extract the first frame of the video to use as a thumbnail,
         # so that the notebook can be exported as HTML and viewed in contexts where
         # the video itself is not accessible.
         # TODO(aaron-siegel): If the video is backed by a concrete external URL,
         # should we link to that instead?
-        with av.open(file_path) as container:
-            try:
-                thumb = next(container.decode(video=0)).to_image()
-                assert isinstance(thumb, Image.Image)
-                with io.BytesIO() as buffer:
-                    thumb.save(buffer, 'jpeg')
-                    thumb_base64 = base64.b64encode(buffer.getvalue()).decode()
-                    thumb_tag = f'poster="data:image/jpeg;base64,{thumb_base64}"'
-            except Exception:
-                pass
+        thumb = self.extract_first_video_frame(file_path)
+        if thumb is None:
+            thumb_tag = ''
+        else:
+            with io.BytesIO() as buffer:
+                thumb.save(buffer, 'jpeg')
+                thumb_base64 = base64.b64encode(buffer.getvalue()).decode()
+                thumb_tag = f'poster="data:image/jpeg;base64,{thumb_base64}"'
         if self.__num_rows > 1:
             width = 320
         elif self.__num_cols > 1:
@@ -182,6 +203,16 @@ class Formatter:
         </div>
         """
 
+    @classmethod
+    def extract_first_video_frame(cls, file_path: str) -> Image.Image | None:
+        with av.open(file_path) as container:
+            try:
+                img = next(container.decode(video=0)).to_image()
+                assert isinstance(img, Image.Image)
+                return img
+            except Exception:
+                return None
+
     def format_audio(self, file_path: str) -> str:
         return f"""
         <div class="pxt_audio">
@@ -191,29 +222,18 @@ class Formatter:
         </div>
         """
 
-    def format_document(self, file_path: str) -> str:
-        max_width = max_height = 320
+    def format_document(self, file_path: str, max_width: int = 320, max_height: int = 320) -> str:
         # by default, file path will be shown as a link
         inner_element = file_path
         inner_element = html.escape(inner_element)
-        # try generating a thumbnail for different types and use that if successful
-        if file_path.lower().endswith('.pdf'):
-            try:
-                import fitz  # type: ignore[import-untyped]
-
-                doc = fitz.open(file_path)
-                p = doc.get_page_pixmap(0)
-                while p.width > max_width or p.height > max_height:
-                    # shrink(1) will halve each dimension
-                    p.shrink(1)
-                data = p.tobytes(output='jpeg')
-                thumb_base64 = base64.b64encode(data).decode()
-                img_src = f'data:image/jpeg;base64,{thumb_base64}'
-                inner_element = f"""
-                    <img style="object-fit: contain; border: 1px solid black;" src="{img_src}" />
-                """
-            except Exception:
-                logging.warning(f'Failed to produce PDF thumbnail {file_path}. Make sure you have PyMuPDF installed.')
+
+        thumb = self.make_document_thumbnail(file_path, max_width, max_height)
+        if thumb is not None:
+            with io.BytesIO() as buffer:
+                thumb.save(buffer, 'webp')
+                thumb_base64 = base64.b64encode(buffer.getvalue()).decode()
+                thumb_tag = f'data:image/webp;base64,{thumb_base64}'
+            inner_element = f'<img style="object-fit: contain; border: 1px solid black;" src="{thumb_tag}" />'
 
         return f"""
         <div class="pxt_document" style="width:{max_width}px;">
@@ -223,6 +243,24 @@ class Formatter:
         </div>
         """
 
+    @classmethod
+    def make_document_thumbnail(cls, file_path: str, max_width: int = 320, max_height: int = 320) -> Image.Image | None:
+        """
+        Returns a thumbnail image of a document.
+        """
+        if file_path.lower().endswith('.pdf'):
+            try:
+                doc = PdfDocument(file_path)
+                if len(doc) == 0:
+                    return None
+                img = doc[0].render().to_pil()
+                img.thumbnail((max_width, max_height), Image.LANCZOS)
+                return img
+            except Exception:
+                logging.warning(f'Failed to produce PDF thumbnail {file_path}. Make sure you have pypdfium2 installed.')
+
+        return None
+
     @classmethod
     def __create_source_tag(cls, http_address: str, file_path: str) -> str:
         src_url = get_file_uri(http_address, file_path)

pixeltable/utils/gcs_store.py

@@ -0,0 +1,295 @@
+from __future__ import annotations
+
+import logging
+import re
+import urllib.parse
+import uuid
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Iterator
+
+from google.api_core.exceptions import GoogleAPIError
+from google.cloud import storage  # type: ignore[attr-defined]
+from google.cloud.exceptions import Forbidden, NotFound
+from google.cloud.storage.client import Client  # type: ignore[import-untyped]
+
+from pixeltable import env, exceptions as excs
+from pixeltable.utils.object_stores import ObjectPath, ObjectStoreBase, StorageObjectAddress, StorageTarget
+
+if TYPE_CHECKING:
+    from pixeltable.catalog import Column
+
+_logger = logging.getLogger('pixeltable')
+
+
+@env.register_client('gcs_store')
+def _() -> 'Client':
+    """Create and return a GCS client, using default credentials if available,
+    otherwise creating an anonymous client for public buckets.
+    """
+    try:
+        # Create a client with default credentials
+        # Note that if the default credentials have expired, gcloud will still create a client,
+        # which will report the expiry error when it is used.
+        # To create and use an anonymous client, expired credentials must be removed.
+        # For application default credentials, delete the file in ~/.config/gcloud/, or
+        #   gcloud auth application-default revoke
+        # OR
+        # For service account keys, you must delete the downloaded key file.
+        client = storage.Client()
+        return client
+    except Exception:
+        # If no credentials are found, create an anonymous client which can be used for public buckets.
+        client = storage.Client.create_anonymous_client()
+        return client
+
+
+class GCSStore(ObjectStoreBase):
+    """Class to handle Google Cloud Storage operations."""
+
+    # URI of the GCS bucket in the format gs://bucket_name/prefix/
+    # Always ends with a slash
+    __base_uri: str
+
+    # bucket name extracted from the URI
+    __bucket_name: str
+
+    # prefix path within the bucket, either empty or ending with a slash
+    __prefix_name: str
+
+    # The parsed form of the given destination address
+    soa: StorageObjectAddress
+
+    def __init__(self, soa: StorageObjectAddress):
+        assert soa.storage_target == StorageTarget.GCS_STORE, f'Expected storage_target "gs", got {soa.storage_target}'
+        self.soa = soa
+        self.__base_uri = soa.prefix_free_uri + soa.prefix
+        self.__bucket_name = soa.container
+        self.__prefix_name = soa.prefix
+
+    @classmethod
+    def client(cls) -> 'Client':
+        """Return the GCS client."""
+        return env.Env.get().get_client('gcs_store')
+
+    @property
+    def bucket_name(self) -> str:
+        """Return the bucket name from the base URI."""
+        return self.__bucket_name
+
+    @property
+    def prefix(self) -> str:
+        """Return the prefix from the base URI."""
+        return self.__prefix_name
+
+    def validate(self, error_col_name: str) -> str | None:
+        """
+        Checks if the URI exists.
+
+        Returns:
+            str: The base URI if the GCS bucket exists and is accessible, None otherwise.
+        """
+        try:
+            client = self.client()
+            bucket = client.bucket(self.bucket_name)
+            blobs = bucket.list_blobs(max_results=1)
+            # This will raise an exception if the destination doesn't exist or cannot be listed
+            _ = list(blobs)  # Force evaluation to check access
+            return self.__base_uri
+        except (NotFound, Forbidden, GoogleAPIError) as e:
+            self.handle_gcs_error(e, self.bucket_name, f'validate bucket {error_col_name}')
+        return None
+
+    def _prepare_uri_raw(self, tbl_id: uuid.UUID, col_id: int, tbl_version: int, ext: str | None = None) -> str:
+        """
+        Construct a new, unique URI for a persisted media file.
+        """
+        prefix, filename = ObjectPath.create_prefix_raw(tbl_id, col_id, tbl_version, ext)
+        parent = f'{self.__base_uri}{prefix}'
+        return f'{parent}/{filename}'
+
+    def _prepare_uri(self, col: Column, ext: str | None = None) -> str:
+        """
+        Construct a new, unique URI for a persisted media file.
+        """
+        assert col.get_tbl() is not None, 'Column must be associated with a table'
+        return self._prepare_uri_raw(col.get_tbl().id, col.id, col.get_tbl().version, ext=ext)
+
+    def copy_local_file(self, col: Column, src_path: Path) -> str:
+        """Copy a local file, and return its new URL"""
+        new_file_uri = self._prepare_uri(col, ext=src_path.suffix)
+        parsed = urllib.parse.urlparse(new_file_uri)
+        blob_name = parsed.path.lstrip('/')
+
+        try:
+            client = self.client()
+            bucket = client.bucket(self.bucket_name)
+            blob = bucket.blob(blob_name)
+            blob.upload_from_filename(str(src_path))
+            _logger.debug(f'Media Storage: copied {src_path} to {new_file_uri}')
+            return new_file_uri
+        except GoogleAPIError as e:
+            self.handle_gcs_error(e, self.bucket_name, f'upload file {src_path}')
+            raise
+
+    def copy_object_to_local_file(self, src_path: str, dest_path: Path) -> None:
+        """Copies an object to a local file. Thread safe"""
+        try:
+            client = self.client()
+            bucket = client.bucket(self.bucket_name)
+            blob = bucket.blob(self.prefix + src_path)
+            blob.download_to_filename(str(dest_path))
+        except GoogleAPIError as e:
+            self.handle_gcs_error(e, self.bucket_name, f'download file {src_path}')
+            raise
+
+    def _get_filtered_objects(self, bucket: Any, tbl_id: uuid.UUID, tbl_version: int | None = None) -> Iterator:
+        """Private method to get filtered objects for a table, optionally filtered by version.
+
+        Args:
+            tbl_id: Table UUID to filter by
+            tbl_version: Optional table version to filter by
+
+        Returns:
+            Tuple of (iterator over GCS objects matching the criteria, bucket object)
+        """
+        table_prefix = ObjectPath.table_prefix(tbl_id)
+        prefix = f'{self.prefix}{table_prefix}/'
+
+        if tbl_version is None:
+            # Return all blobs with the table prefix
+            blob_iterator = bucket.list_blobs(prefix=prefix)
+        else:
+            # Filter by both table_id and table_version using the ObjectPath pattern
+            # Pattern: tbl_id_col_id_version_uuid
+            version_pattern = re.compile(rf'{re.escape(table_prefix)}_\d+_{re.escape(str(tbl_version))}_[0-9a-fA-F]+.*')
+            # Return filtered collection - this still uses lazy loading
+            all_blobs = bucket.list_blobs(prefix=prefix)
+            blob_iterator = (blob for blob in all_blobs if version_pattern.match(blob.name.split('/')[-1]))
+
+        return blob_iterator
+
+    def count(self, tbl_id: uuid.UUID, tbl_version: int | None = None) -> int:
+        """Count the number of files belonging to tbl_id. If tbl_version is not None,
+        count only those files belonging to the specified tbl_version.
+
+        Args:
+            tbl_id: Table UUID to count objects for
+            tbl_version: Optional table version to filter by
+
+        Returns:
+            Number of objects matching the criteria
+        """
+        assert tbl_id is not None
+
+        try:
+            client = self.client()
+            bucket = client.bucket(self.bucket_name)
+
+            blob_iterator = self._get_filtered_objects(bucket, tbl_id, tbl_version)
+
+            return sum(1 for _ in blob_iterator)
+
+        except GoogleAPIError as e:
+            self.handle_gcs_error(e, self.bucket_name, f'setup iterator {self.prefix}')
+            raise
+
+    def delete(self, tbl_id: uuid.UUID, tbl_version: int | None = None) -> int:
+        """Delete all files belonging to tbl_id. If tbl_version is not None, delete
+        only those files belonging to the specified tbl_version.
+
+        Args:
+            tbl_id: Table UUID to delete objects for
+            tbl_version: Optional table version to filter by
+
+        Returns:
+            Number of objects deleted
+        """
+        assert tbl_id is not None
+        total_deleted = 0
+
+        try:
+            client = self.client()
+            bucket = client.bucket(self.bucket_name)
+            blob_iterator = self._get_filtered_objects(bucket, tbl_id, tbl_version)
+
+            # Collect blob names for batch deletion
+            blobs_to_delete = []
+
+            for blob in blob_iterator:
+                blobs_to_delete.append(blob)
+
+                # Process in batches for efficiency
+                if len(blobs_to_delete) >= 100:
+                    with client.batch():
+                        for b in blobs_to_delete:
+                            b.delete()
+                    total_deleted += len(blobs_to_delete)
+                    blobs_to_delete = []
+
+            # Delete any remaining blobs in the final batch
+            if len(blobs_to_delete) > 0:
+                with client.batch():
+                    for b in blobs_to_delete:
+                        b.delete()
+                total_deleted += len(blobs_to_delete)
+
+            return total_deleted
+
+        except GoogleAPIError as e:
+            self.handle_gcs_error(e, self.bucket_name, f'deleting with {self.prefix}')
+            raise
+
+    def list_objects(self, return_uri: bool, n_max: int = 10) -> list[str]:
+        """Return a list of objects found in the specified destination bucket.
+        Each returned object includes the full set of prefixes.
+        if return_uri is True, full URI's are returned; otherwise, just the object keys.
+        """
+        p = self.soa.prefix_free_uri if return_uri else ''
+        gcs_client = self.client()
+        r: list[str] = []
+
+        try:
+            bucket = gcs_client.bucket(self.bucket_name)
+            # List blobs with the given prefix, limiting to n_max
+            blobs = bucket.list_blobs(prefix=self.prefix, max_results=n_max)
+
+            for blob in blobs:
+                r.append(f'{p}{blob.name}')
+                if len(r) >= n_max:
+                    break
+
+        except GoogleAPIError as e:
+            self.handle_gcs_error(e, self.bucket_name, f'list objects from {self.prefix}')
+        return r
+
+    def create_presigned_url(self, soa: StorageObjectAddress, expiration_seconds: int) -> str:
+        """Create a presigned URL for downloading an object from GCS."""
+        if not soa.has_object:
+            raise excs.Error(f'StorageObjectAddress does not contain an object name: {soa}')
+
+        gcs_client = self.client()
+        bucket = gcs_client.bucket(soa.container)
+        blob = bucket.blob(soa.key)
+
+        presigned_url = blob.generate_signed_url(version='v4', expiration=expiration_seconds, method='GET')
+        return presigned_url
+
+    @classmethod
+    def handle_gcs_error(cls, e: Exception, bucket_name: str, operation: str = '', *, ignore_404: bool = False) -> None:
+        """Handle GCS-specific errors and convert them to appropriate exceptions"""
+        if isinstance(e, NotFound):
+            if ignore_404:
+                return
+            raise excs.Error(f'Bucket or object {bucket_name} not found during {operation}: {str(e)!r}')
+        elif isinstance(e, Forbidden):
+            raise excs.Error(f'Access denied to bucket {bucket_name} during {operation}: {str(e)!r}')
+        elif isinstance(e, GoogleAPIError):
+            # Handle other Google API errors
+            error_message = str(e)
+            if 'Precondition' in error_message:
+                raise excs.Error(f'Precondition failed for bucket {bucket_name} during {operation}: {error_message}')
+            else:
+                raise excs.Error(f'Error during {operation} in bucket {bucket_name}: {error_message}')
+        else:
+            # Generic error handling
+            raise excs.Error(f'Unexpected error during {operation} in bucket {bucket_name}: {str(e)!r}')