zerobucket 0.2.0__tar.gz → 0.4.0__tar.gz

{zerobucket-0.2.0 → zerobucket-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: zerobucket
-Version: 0.2.0
+Version: 0.4.0
 Summary: Database-native image storage. Your database. Your images. Zero buckets.
 Project-URL: Homepage, https://github.com/KedarGhadyalji/ZeroBucket
 Project-URL: Repository, https://github.com/KedarGhadyalji/ZeroBucket
@@ -27,10 +27,13 @@ Requires-Dist: psycopg[binary]>=3.1
 Provides-Extra: dev
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: numpy>=1.26; extra == 'dev'
+Requires-Dist: pillow-heif>=0.13; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
 Requires-Dist: scikit-image>=0.22; extra == 'dev'
+Provides-Extra: heic
+Requires-Dist: pillow-heif>=0.13; extra == 'heic'
 Description-Content-Type: text/markdown
 
 # ZeroBucket
@@ -146,8 +149,10 @@ on GitHub for the full methodology.
 
 ## What it validates
 
-- **Format**: JPEG, PNG, WebP -- detected from actual file content, never
-  from filename extension or a client-supplied `Content-Type` header.
+- **Format**: JPEG, PNG, WebP built in, plus HEIC/HEIF (iPhone photos) via
+  the optional `pip install zerobucket[heic]` extra -- detected from
+  actual file content, never from filename extension or a client-supplied
+  `Content-Type` header.
 - **Corruption**: truncated or malformed images are decoded and rejected
   before they reach the database.
 - **Decompression bombs**: a tiny compressed file that decodes to an
@@ -156,6 +161,18 @@ on GitHub for the full methodology.
   [benchmark results](https://github.com/KedarGhadyalji/ZeroBucket/blob/main/benchmarks/RESULTS.md)
   for why.
 
+## Transactions
+
+By default, `put()`/`get()`/`delete()` each use their own independent
+database connection -- **not** your application's own transaction, even
+against the same database. Pass your own open `psycopg` connection via
+`connection=` to make a write participate in your transaction (e.g. "user
+
+- avatar, atomically, or neither"). See the
+  [Transactions section](https://github.com/KedarGhadyalji/ZeroBucket#transactions)
+  on GitHub for a worked example -- this was verified by direct experiment
+  during development, not assumed.
+
 ## Limitations (read before using in production)
 
 - **Not built for large files or high-volume media.** Full images are

{zerobucket-0.2.0 → zerobucket-0.4.0}/README.md

@@ -111,8 +111,10 @@ on GitHub for the full methodology.
 
 ## What it validates
 
-- **Format**: JPEG, PNG, WebP -- detected from actual file content, never
-  from filename extension or a client-supplied `Content-Type` header.
+- **Format**: JPEG, PNG, WebP built in, plus HEIC/HEIF (iPhone photos) via
+  the optional `pip install zerobucket[heic]` extra -- detected from
+  actual file content, never from filename extension or a client-supplied
+  `Content-Type` header.
 - **Corruption**: truncated or malformed images are decoded and rejected
   before they reach the database.
 - **Decompression bombs**: a tiny compressed file that decodes to an
@@ -121,6 +123,18 @@ on GitHub for the full methodology.
   [benchmark results](https://github.com/KedarGhadyalji/ZeroBucket/blob/main/benchmarks/RESULTS.md)
   for why.
 
+## Transactions
+
+By default, `put()`/`get()`/`delete()` each use their own independent
+database connection -- **not** your application's own transaction, even
+against the same database. Pass your own open `psycopg` connection via
+`connection=` to make a write participate in your transaction (e.g. "user
+
+- avatar, atomically, or neither"). See the
+  [Transactions section](https://github.com/KedarGhadyalji/ZeroBucket#transactions)
+  on GitHub for a worked example -- this was verified by direct experiment
+  during development, not assumed.
+
 ## Limitations (read before using in production)
 
 - **Not built for large files or high-volume media.** Full images are

{zerobucket-0.2.0 → zerobucket-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "zerobucket"
-version = "0.2.0"
+version = "0.4.0"
 description = "Database-native image storage. Your database. Your images. Zero buckets."
 readme = "README.md"
 license = "MIT"
@@ -31,6 +31,9 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+heic = [
+    "pillow-heif>=0.13",
+]
 dev = [
     "pytest>=8.0",
     "pytest-cov>=5.0",
@@ -38,6 +41,7 @@ dev = [
     "mypy>=1.10",
     "scikit-image>=0.22",
     "numpy>=1.26",
+    "pillow-heif>=0.13",
 ]
 
 [project.urls]

{zerobucket-0.2.0 → zerobucket-0.4.0}/src/zerobucket/__init__.py

@@ -19,7 +19,7 @@ from .exceptions import (
 from .optimization import OptimizationResult
 from .types import Image, ImageMetadata
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"
 
 __all__ = [
     "ZeroBucket",

{zerobucket-0.2.0 → zerobucket-0.4.0}/src/zerobucket/adapters/base.py

@@ -7,6 +7,17 @@ zerobucket.client, above this layer.
 
 This separation is what makes a future object-storage backend a real
 drop-in replacement rather than a rewrite.
+
+Every method accepts an optional `connection`. When None (the default),
+the backend uses its own internal pool -- each call commits independently
+on its own connection, exactly as before. When a connection is provided,
+the backend uses it directly and does NOT commit or roll it back -- that
+becomes the caller's responsibility, which is what lets an operation
+participate in the caller's own transaction (see client.py's put() docs
+for why this matters and a worked example). `connection` is intentionally
+typed as `object` here rather than a Postgres-specific type, since this
+interface is meant to stay backend-agnostic; concrete adapters narrow the
+type in their own implementation.
 """
 
 from __future__ import annotations
@@ -56,23 +67,28 @@ class StorageBackend(ABC):
         width: int | None,
         height: int | None,
         checksum_sha256: str,
+        connection: object | None = None,
     ) -> str:
         """Persist a record and return its generated id."""
 
     @abstractmethod
-    def get(self, image_id: str) -> StoredRecord | None:
+    def get(
+        self, image_id: str, *, connection: object | None = None
+    ) -> StoredRecord | None:
         """Fetch a full record including bytes, or None if it doesn't exist."""
 
     @abstractmethod
-    def get_metadata(self, image_id: str) -> StoredRecordMetadata | None:
+    def get_metadata(
+        self, image_id: str, *, connection: object | None = None
+    ) -> StoredRecordMetadata | None:
         """Fetch metadata only (no bytes), or None if it doesn't exist."""
 
     @abstractmethod
-    def delete(self, image_id: str) -> bool:
+    def delete(self, image_id: str, *, connection: object | None = None) -> bool:
         """Delete a record. Returns True if a record was deleted, False if it didn't exist."""
 
     @abstractmethod
-    def exists(self, image_id: str) -> bool:
+    def exists(self, image_id: str, *, connection: object | None = None) -> bool:
         """Return whether a record with this id exists."""
 
     @abstractmethod

{zerobucket-0.2.0 → zerobucket-0.4.0}/src/zerobucket/adapters/postgres.py

@@ -6,11 +6,17 @@ parameterized; nothing is ever built via string concatenation.
 
 from __future__ import annotations
 
+from contextlib import contextmanager
+from typing import TYPE_CHECKING
+
 from psycopg_pool import ConnectionPool
 
 from ..exceptions import StorageError
 from .base import StorageBackend, StoredRecord, StoredRecordMetadata
 
+if TYPE_CHECKING:
+    import psycopg
+
 _SCHEMA = """
 CREATE TABLE IF NOT EXISTS zerobucket_images (
     id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
@@ -85,6 +91,26 @@ class PostgresBackend(StorageBackend):
         except Exception as exc:  # noqa: BLE001
             raise StorageError(f"Migration failed: {exc}") from exc
 
+    @contextmanager
+    def _cursor(self, connection: psycopg.Connection | None):
+        """Yield a cursor, either on the caller's own connection or a
+        pooled one.
+
+        When `connection` is provided, we use it directly and do NOT
+        commit or roll it back -- that's the caller's responsibility,
+        and is precisely what lets a put()/delete() participate in the
+        caller's own transaction (see client.py). When `connection` is
+        None, we fall back to the internal pool exactly as before: each
+        call gets its own connection and commits independently on clean
+        exit.
+        """
+        if connection is not None:
+            with connection.cursor() as cur:
+                yield cur
+        else:
+            with self._pool.connection() as conn, conn.cursor() as cur:
+                yield cur
+
     def put(
         self,
         *,
@@ -95,9 +121,10 @@ class PostgresBackend(StorageBackend):
         width: int | None,
         height: int | None,
         checksum_sha256: str,
+        connection: psycopg.Connection | None = None,
     ) -> str:
         try:
-            with self._pool.connection() as conn, conn.cursor() as cur:
+            with self._cursor(connection) as cur:
                 params = (
                     data,
                     mime_type,
@@ -113,9 +140,11 @@ class PostgresBackend(StorageBackend):
         except Exception as exc:  # noqa: BLE001
             raise StorageError(f"Failed to store image: {exc}") from exc
 
-    def get(self, image_id: str) -> StoredRecord | None:
+    def get(
+        self, image_id: str, *, connection: psycopg.Connection | None = None
+    ) -> StoredRecord | None:
         try:
-            with self._pool.connection() as conn, conn.cursor() as cur:
+            with self._cursor(connection) as cur:
                 cur.execute(_SELECT_FULL, (image_id,))
                 row = cur.fetchone()
         except Exception as exc:  # noqa: BLE001
@@ -133,9 +162,11 @@ class PostgresBackend(StorageBackend):
             checksum_sha256=row[7],
         )
 
-    def get_metadata(self, image_id: str) -> StoredRecordMetadata | None:
+    def get_metadata(
+        self, image_id: str, *, connection: psycopg.Connection | None = None
+    ) -> StoredRecordMetadata | None:
         try:
-            with self._pool.connection() as conn, conn.cursor() as cur:
+            with self._cursor(connection) as cur:
                 cur.execute(_SELECT_METADATA, (image_id,))
                 row = cur.fetchone()
         except Exception as exc:  # noqa: BLE001
@@ -152,17 +183,21 @@ class PostgresBackend(StorageBackend):
             checksum_sha256=row[6],
         )
 
-    def delete(self, image_id: str) -> bool:
+    def delete(
+        self, image_id: str, *, connection: psycopg.Connection | None = None
+    ) -> bool:
         try:
-            with self._pool.connection() as conn, conn.cursor() as cur:
+            with self._cursor(connection) as cur:
                 cur.execute(_DELETE, (image_id,))
                 return cur.rowcount > 0
         except Exception as exc:  # noqa: BLE001
             raise StorageError(f"Failed to delete image: {exc}") from exc
 
-    def exists(self, image_id: str) -> bool:
+    def exists(
+        self, image_id: str, *, connection: psycopg.Connection | None = None
+    ) -> bool:
         try:
-            with self._pool.connection() as conn, conn.cursor() as cur:
+            with self._cursor(connection) as cur:
                 cur.execute(_EXISTS, (image_id,))
                 return cur.fetchone() is not None
         except Exception as exc:  # noqa: BLE001

{zerobucket-0.2.0 → zerobucket-0.4.0}/src/zerobucket/client.py

@@ -77,6 +77,7 @@ class ZeroBucket:
         max_width: int | None = None,
         format: str | None = None,
         quality: int | None = None,
+        connection: object | None = None,
     ) -> str:
         """Validate, optionally optimize, and store an image. Returns its id.
 
@@ -93,7 +94,8 @@ class ZeroBucket:
                 bytes are stored as-is.
             max_width: Downscale if wider than this (aspect ratio
                 preserved). Only applies when optimize=True.
-            format: Re-encode target -- "jpeg", "png", or "webp". None
+            format: Re-encode target -- "jpeg", "png", "webp", or
+                "heic"/"heif". None
                 keeps the original format. Only applies when
                 optimize=True. Note: quality has no effect when the
                 target (or original) format is PNG -- PNG has no lossy
@@ -103,6 +105,17 @@ class ZeroBucket:
                 zerobucket.optimization for the reasoning and
                 tests/test_optimization.py for the SSIM regression test
                 that enforces it). Only applies when optimize=True.
+            connection: Advanced -- pass your own open psycopg connection
+                (one you're already using for other writes in the same
+                transaction) to make this put() commit or roll back
+                together with the rest of that transaction, instead of
+                committing independently on ZeroBucket's own internal
+                pool. Without this, put() ALWAYS commits on its own,
+                regardless of what your application does afterward --
+                see the README's "Transactions" section for a worked
+                example and why this matters (e.g. "create a user record
+                and store their avatar atomically" only works if you
+                pass connection= here).
         """
         data, resolved_filename = _read_image_input(image, filename)
 
@@ -147,11 +160,17 @@ class ZeroBucket:
             width=width,
             height=height,
             checksum_sha256=checksum,
+            connection=connection,
         )
 
-    def get(self, image_id: str) -> Image:
-        """Retrieve a full image, including bytes. Raises ImageNotFoundError if missing."""
-        record = self._backend.get(image_id)
+    def get(self, image_id: str, *, connection: object | None = None) -> Image:
+        """Retrieve a full image, including bytes. Raises ImageNotFoundError if missing.
+
+        connection: Advanced -- see put()'s docstring. Passing the same
+            open transaction lets you read back a row you just wrote in
+            that same transaction, before it's committed.
+        """
+        record = self._backend.get(image_id, connection=connection)
         if record is None:
             raise ImageNotFoundError(image_id)
         return Image(
@@ -164,9 +183,14 @@ class ZeroBucket:
             checksum_sha256=record.checksum_sha256,
         )
 
-    def metadata(self, image_id: str) -> ImageMetadata:
-        """Retrieve image metadata without pulling the (potentially large) bytes."""
-        record = self._backend.get_metadata(image_id)
+    def metadata(
+        self, image_id: str, *, connection: object | None = None
+    ) -> ImageMetadata:
+        """Retrieve image metadata without pulling the (potentially large) bytes.
+
+        connection: Advanced -- see put()'s docstring.
+        """
+        record = self._backend.get_metadata(image_id, connection=connection)
         if record is None:
             raise ImageNotFoundError(image_id)
         return ImageMetadata(
@@ -179,13 +203,22 @@ class ZeroBucket:
             checksum_sha256=record.checksum_sha256,
         )
 
-    def exists(self, image_id: str) -> bool:
-        """Return whether an image with this id exists."""
-        return self._backend.exists(image_id)
+    def exists(self, image_id: str, *, connection: object | None = None) -> bool:
+        """Return whether an image with this id exists.
 
-    def delete(self, image_id: str) -> bool:
-        """Delete an image. Returns True if it existed and was deleted, False otherwise."""
-        return self._backend.delete(image_id)
+        connection: Advanced -- see put()'s docstring.
+        """
+        return self._backend.exists(image_id, connection=connection)
+
+    def delete(self, image_id: str, *, connection: object | None = None) -> bool:
+        """Delete an image. Returns True if it existed and was deleted, False otherwise.
+
+        connection: Advanced -- see put()'s docstring. Passing the same
+            open transaction lets a delete() roll back together with the
+            rest of that transaction (e.g. "delete a user and their
+            avatar atomically").
+        """
+        return self._backend.delete(image_id, connection=connection)
 
     def close(self) -> None:
         """Release underlying database connections."""

{zerobucket-0.2.0 → zerobucket-0.4.0}/src/zerobucket/optimization.py

@@ -27,19 +27,30 @@ from dataclasses import dataclass
 from PIL import Image as PILImage
 
 from .exceptions import ImageValidationError
-from .validation import DEFAULT_MAX_PIXELS, SUPPORTED_FORMATS, validate_image
-
-# Canonical MIME type -> Pillow format name, and back. Kept separate from
-# validation.py's version to avoid a circular import; the two must be kept
-# in sync if formats are ever added.
-_MIME_TO_PIL_FORMAT = {
-    "image/jpeg": "JPEG",
-    "image/png": "PNG",
-    "image/webp": "WEBP",
+from .validation import (
+    DEFAULT_MAX_PIXELS,
+    HEIF_SUPPORT_INSTALLED,
+    SUPPORTED_FORMATS,
+    validate_image,
+)
+
+# Normalizes user-facing target_format strings to what Pillow's save()
+# actually expects. Most formats are their own name uppercased, but HEIC
+# is the one exception: Pillow (via pillow-heif) only recognizes the save
+# format string "HEIF", never "HEIC" -- even though "HEIC" is what the
+# file extension and most people call it. Verified empirically; passing
+# format="HEIC" directly to Pillow raises KeyError, not a graceful error.
+_FORMAT_ALIASES = {
+    "HEIC": "HEIF",
 }
 
 DEFAULT_JPEG_QUALITY = 90
 DEFAULT_WEBP_QUALITY = 88
+# NOT measured with the same SSIM methodology as the two defaults above
+# (see benchmarks/COMPRESSION_RESULTS.md) -- this is a reasonable starting
+# point, not a verified claim. Treat it as provisional until it's been
+# through the same measurement process.
+DEFAULT_HEIC_QUALITY = 90
 
 
 @dataclass(frozen=True, slots=True)
@@ -81,9 +92,13 @@ def optimize_image(
             (aspect ratio preserved, LANCZOS resampling -- the sharpest
             standard downscale filter, chosen specifically to avoid
             introducing blur that a cheaper filter like BILINEAR would).
-        target_format: "jpeg", "png", or "webp". None keeps the original
-            format. Converting a PNG to WebP/JPEG is usually the right
-            call when the PNG is actually a photo, not flat-color art.
+        target_format: "jpeg", "png", "webp", or "heic"/"heif". None keeps
+            the original format. Converting a PNG to WebP/JPEG is usually
+            the right call when the PNG is actually a photo, not
+            flat-color art. Converting TO heic requires the optional
+            pillow-heif dependency; if it's missing, this raises
+            ImageValidationError with an install hint rather than
+            producing an unclear internal error.
         quality: 1-100. Only meaningful for JPEG/WebP output -- PNG has
             no lossy quality knob and this is ignored for PNG targets.
             None uses DEFAULT_JPEG_QUALITY / DEFAULT_WEBP_QUALITY.
@@ -117,8 +132,12 @@ def optimize_image(
         working = img
 
         output_format = (target_format or source_format or "JPEG").upper()
+        output_format = _FORMAT_ALIASES.get(output_format, output_format)
         if output_format == "JPEG" and working.mode in ("RGBA", "P", "LA"):
             working = working.convert("RGB")
+        # Note: unlike JPEG, HEIF encoding via pillow-heif handles RGBA
+        # source images fine (verified empirically) -- no forced conversion
+        # needed there.
 
         if max_width is not None and working.width > max_width:
             ratio = max_width / working.width
@@ -138,8 +157,15 @@ def optimize_image(
             save_kwargs = {
                 "quality": quality or DEFAULT_WEBP_QUALITY,
                 "method": 6,  # slowest, best-compression effort; fine for
-                               # a one-time encode on upload, not a hot path
+                # a one-time encode on upload, not a hot path
             }
+        elif output_format == "HEIF":
+            if not HEIF_SUPPORT_INSTALLED:
+                raise ImageValidationError(
+                    "Converting to HEIC/HEIF requires an optional dependency. "
+                    "Install it with: pip install zerobucket[heic]"
+                )
+            save_kwargs = {"quality": quality or DEFAULT_HEIC_QUALITY}
         elif output_format == "PNG":
             # No lossy quality knob for PNG. `quality` is silently ignored
             # here by design -- see the docstring above.
@@ -169,4 +195,4 @@ def optimize_image(
         height=revalidated.height,
         size_bytes=revalidated.size_bytes,
         original_size_bytes=original_size,
-    )
+    )

{zerobucket-0.2.0 → zerobucket-0.4.0}/src/zerobucket/validation.py

@@ -15,6 +15,7 @@ from PIL import Image as PILImage
 from .exceptions import (
     CorruptedImageError,
     ImageTooLargeError,
+    ImageValidationError,
     UnsupportedFormatError,
 )
 
@@ -26,6 +27,20 @@ _FORMAT_TO_MIME = {
     "WEBP": "image/webp",
 }
 
+# HEIC/HEIF support is optional (pip install zerobucket[heic]) because
+# pillow-heif pulls in a native libheif wheel -- not everyone needs it, and
+# we don't want it in the default install. If it's present, registering the
+# opener makes Image.open()/save() handle HEIC transparently everywhere
+# else in this codebase; no other code needs to know HEIC exists.
+try:
+    import pillow_heif
+
+    pillow_heif.register_heif_opener()
+    _FORMAT_TO_MIME["HEIF"] = "image/heic"
+    HEIF_SUPPORT_INSTALLED = True
+except ImportError:
+    HEIF_SUPPORT_INSTALLED = False
+
 SUPPORTED_FORMATS = frozenset(_FORMAT_TO_MIME)
 
 # Guard against decompression bombs: reject images that would decode to
@@ -44,6 +59,22 @@ class ValidatedImage:
     size_bytes: int
 
 
+def _looks_like_heic(data: bytes) -> bool:
+    """Sniff for an ISO-BMFF 'ftyp' box with a HEIC/HEIF brand.
+
+    Used only to give a clear, actionable error when pillow-heif isn't
+    installed -- without this, a genuinely valid HEIC file would fail with
+    a generic "could not decode image" message that looks like corruption
+    rather than a missing optional dependency.
+    """
+    if len(data) < 12:
+        return False
+    if data[4:8] != b"ftyp":
+        return False
+    brand = data[8:12]
+    return brand in (b"heic", b"heix", b"hevc", b"heim", b"heis", b"mif1", b"msf1")
+
+
 def validate_image(
     data: bytes,
     *,
@@ -53,8 +84,9 @@ def validate_image(
 ) -> ValidatedImage:
     """Validate raw image bytes and return derived metadata.
 
-    Raises ImageTooLargeError, UnsupportedFormatError, or CorruptedImageError.
-    Never raises for reasons unrelated to the image itself.
+    Raises ImageTooLargeError, UnsupportedFormatError, ImageValidationError,
+    or CorruptedImageError. Never raises for reasons unrelated to the image
+    itself.
     """
     size_bytes = len(data)
     if size_bytes > max_bytes:
@@ -62,6 +94,12 @@ def validate_image(
     if size_bytes == 0:
         raise CorruptedImageError("Image data is empty")
 
+    if not HEIF_SUPPORT_INSTALLED and _looks_like_heic(data):
+        raise ImageValidationError(
+            "This looks like a HEIC/HEIF image, which requires an optional "
+            "dependency. Install it with: pip install zerobucket[heic]"
+        )
+
     # Pillow's own decompression-bomb guard, in pixels (not compressed bytes).
     # We set it per-call rather than mutating the module-global so concurrent
     # validate_image() calls with different limits don't race each other.
@@ -91,7 +129,9 @@ def validate_image(
             with PILImage.open(io.BytesIO(data)) as img:
                 img.load()
         except Exception as exc:  # noqa: BLE001
-            raise CorruptedImageError(f"Image data is truncated or corrupted: {exc}") from exc
+            raise CorruptedImageError(
+                f"Image data is truncated or corrupted: {exc}"
+            ) from exc
     finally:
         PILImage.MAX_IMAGE_PIXELS = original_max_pixels
 

{zerobucket-0.2.0 → zerobucket-0.4.0}/tests/test_optimization.py

@@ -33,6 +33,7 @@ from zerobucket.optimization import (
     DEFAULT_WEBP_QUALITY,
     optimize_image,
 )
+from zerobucket.validation import HEIF_SUPPORT_INSTALLED
 
 from .photo_fixtures import ALL_FIXTURES
 
@@ -79,7 +80,9 @@ def test_default_jpeg_quality_meets_content_appropriate_floor(fixture_name):
     original = fixture_fn()
     floor = SSIM_FLOOR_BY_FIXTURE[fixture_name]
 
-    result = optimize_image(original, target_format="jpeg", max_bytes=_MAX_BYTES)
+    result = optimize_image(
+        original, target_format="jpeg", max_bytes=_MAX_BYTES
+    )
 
     score = _compute_ssim(original, result.data)
     assert score >= floor, (
@@ -94,7 +97,9 @@ def test_default_webp_quality_meets_content_appropriate_floor(fixture_name):
     original = fixture_fn()
     floor = SSIM_FLOOR_BY_FIXTURE[fixture_name]
 
-    result = optimize_image(original, target_format="webp", max_bytes=_MAX_BYTES)
+    result = optimize_image(
+        original, target_format="webp", max_bytes=_MAX_BYTES
+    )
 
     score = _compute_ssim(original, result.data)
     assert score >= floor, (
@@ -111,10 +116,7 @@ def test_low_quality_actually_degrades_ssim():
     original = ALL_FIXTURES["busy_texture"]()
 
     good = optimize_image(
-        original,
-        target_format="jpeg",
-        quality=DEFAULT_JPEG_QUALITY,
-        max_bytes=_MAX_BYTES,
+        original, target_format="jpeg", quality=DEFAULT_JPEG_QUALITY, max_bytes=_MAX_BYTES
     )
     bad = optimize_image(
         original, target_format="jpeg", quality=15, max_bytes=_MAX_BYTES
@@ -215,3 +217,51 @@ def test_optimized_output_size_still_enforces_max_bytes():
     original = ALL_FIXTURES["busy_texture"]()
     with pytest.raises(ImageTooLargeError):
         optimize_image(original, target_format="jpeg", quality=100, max_bytes=100)
+
+
+@pytest.mark.skipif(not HEIF_SUPPORT_INSTALLED, reason="pillow-heif not installed")
+def test_heic_source_converts_to_jpeg():
+    """The main real-world use case: iPhone uploads HEIC, app wants JPEG
+    for broad browser compatibility."""
+    img = PILImage.new("RGB", (200, 150), color=(100, 150, 200))
+    buf = io.BytesIO()
+    img.save(buf, format="HEIF", quality=95)
+    original = buf.getvalue()
+
+    result = optimize_image(original, target_format="jpeg", max_bytes=_MAX_BYTES)
+    assert result.mime_type == "image/jpeg"
+    assert result.width == 200
+    assert result.height == 150
+
+
+@pytest.mark.skipif(not HEIF_SUPPORT_INSTALLED, reason="pillow-heif not installed")
+def test_jpeg_source_converts_to_heic():
+    """Reverse direction: also supported, since it's effectively free
+    through Pillow's plugin architecture, even though the main real-world
+    need is HEIC-in, not HEIC-out."""
+    original = ALL_FIXTURES["gradient_landscape"]()
+    result = optimize_image(original, target_format="heic", max_bytes=_MAX_BYTES)
+    assert result.mime_type == "image/heic"
+
+
+@pytest.mark.skipif(not HEIF_SUPPORT_INSTALLED, reason="pillow-heif not installed")
+def test_heic_target_accepts_both_heic_and_heif_spelling():
+    """Users will naturally type 'heic' (the file extension they know),
+    not 'heif' (Pillow's internal format name) -- both must work."""
+    original = ALL_FIXTURES["flat_graphic"]()
+    result_heic = optimize_image(original, target_format="heic", max_bytes=_MAX_BYTES)
+    result_heif = optimize_image(original, target_format="heif", max_bytes=_MAX_BYTES)
+    assert result_heic.mime_type == "image/heic"
+    assert result_heif.mime_type == "image/heic"
+
+
+def test_heic_target_without_optional_dependency_gives_actionable_error(monkeypatch):
+    """Requesting format='heic' without pillow-heif installed should fail
+    clearly, not with a raw Pillow KeyError."""
+    import zerobucket.optimization as optimization_module
+
+    monkeypatch.setattr(optimization_module, "HEIF_SUPPORT_INSTALLED", False)
+
+    original = ALL_FIXTURES["flat_graphic"]()
+    with pytest.raises(ImageValidationError, match=r"pip install zerobucket\[heic\]"):
+        optimize_image(original, target_format="heic", max_bytes=_MAX_BYTES)

zerobucket-0.4.0/tests/test_transactions.py

@@ -0,0 +1,151 @@
+"""Tests for the connection= parameter: does put()/delete() actually
+participate in the caller's own transaction when given one, and does the
+default behavior (no connection given) remain independently-committing,
+exactly as it always has?
+
+These mirror a real experiment run during development: without
+connection=, a put() survives even when the caller's own separate
+transaction rolls back -- proving the two are NOT atomic by default. That
+finding is what motivated this feature; these tests lock in both the old
+default behavior and the new opt-in behavior so neither regresses.
+"""
+
+from __future__ import annotations
+
+import io
+
+import psycopg
+from PIL import Image as PILImage
+
+
+def _jpeg_bytes() -> bytes:
+    img = PILImage.new("RGB", (40, 30), color=(10, 20, 30))
+    buf = io.BytesIO()
+    img.save(buf, format="JPEG")
+    return buf.getvalue()
+
+
+def test_put_without_connection_commits_independently_of_caller_transaction(images):
+    """Default (unchanged) behavior: put() ALWAYS commits on its own,
+    regardless of what the caller's own separate connection does
+    afterward. This is the current, real behavior -- not an aspiration --
+    and this test exists specifically so it can't silently change without
+    someone noticing."""
+    from tests.conftest import TEST_DATABASE_URL
+
+    app_conn = psycopg.connect(TEST_DATABASE_URL)
+    app_conn.autocommit = False
+    try:
+        with app_conn.cursor() as cur:
+            cur.execute(
+                "CREATE TABLE IF NOT EXISTS _test_app_scratch (id serial primary key);"
+            )
+        app_conn.commit()
+
+        with app_conn.cursor() as cur:
+            cur.execute("INSERT INTO _test_app_scratch DEFAULT VALUES;")
+
+        image_id = images.put(_jpeg_bytes())  # no connection= passed
+
+        app_conn.rollback()
+
+        with app_conn.cursor() as cur:
+            cur.execute("SELECT count(*) FROM _test_app_scratch;")
+            assert cur.fetchone()[0] == 0  # app's own insert was rolled back
+
+        # But the image was NOT rolled back -- it committed independently.
+        assert images.exists(image_id) is True
+    finally:
+        with app_conn.cursor() as cur:
+            cur.execute("DROP TABLE IF EXISTS _test_app_scratch;")
+        app_conn.commit()
+        app_conn.close()
+
+
+def test_put_with_connection_rolls_back_with_caller_transaction(images):
+    """The new opt-in behavior: passing connection= makes put() a real
+    part of the caller's transaction -- if the caller rolls back, the
+    image row is gone too, same as any other write in that transaction."""
+    from tests.conftest import TEST_DATABASE_URL
+
+    app_conn = psycopg.connect(TEST_DATABASE_URL)
+    app_conn.autocommit = False
+    try:
+        image_id = images.put(_jpeg_bytes(), connection=app_conn)
+
+        # Readable within the SAME still-open transaction (read-your-writes).
+        assert images.exists(image_id, connection=app_conn) is True
+
+        app_conn.rollback()
+
+        # After rollback, the image must be gone -- it was never committed.
+        assert images.exists(image_id) is False
+    finally:
+        app_conn.close()
+
+
+def test_put_with_connection_commits_with_caller_transaction(images):
+    """The success path: passing connection= and then committing the
+    caller's own transaction commits the image too."""
+    from tests.conftest import TEST_DATABASE_URL
+
+    app_conn = psycopg.connect(TEST_DATABASE_URL)
+    app_conn.autocommit = False
+    try:
+        image_id = images.put(_jpeg_bytes(), connection=app_conn)
+        app_conn.commit()
+
+        assert images.exists(image_id) is True
+        images.delete(image_id)
+    finally:
+        app_conn.close()
+
+
+def test_delete_with_connection_rolls_back_with_caller_transaction(images):
+    """Symmetric case for delete(): a delete() done inside a caller's
+    transaction is undone if that transaction rolls back."""
+    from tests.conftest import TEST_DATABASE_URL
+
+    image_id = images.put(_jpeg_bytes())
+    assert images.exists(image_id) is True
+
+    app_conn = psycopg.connect(TEST_DATABASE_URL)
+    app_conn.autocommit = False
+    try:
+        images.delete(image_id, connection=app_conn)
+        # Within the same open transaction, it looks deleted.
+        assert images.exists(image_id, connection=app_conn) is False
+
+        app_conn.rollback()
+
+        # After rollback, the image is back -- the delete never committed.
+        assert images.exists(image_id) is True
+    finally:
+        app_conn.close()
+        images.delete(image_id)
+
+
+def test_get_with_connection_sees_uncommitted_write_in_same_transaction(images):
+    """Read-your-writes: get() with the same open connection can see a
+    row that was put() in that same transaction but not yet committed --
+    proving they really do share one transaction, not just coincidence."""
+    from tests.conftest import TEST_DATABASE_URL
+
+    app_conn = psycopg.connect(TEST_DATABASE_URL)
+    app_conn.autocommit = False
+    try:
+        data = _jpeg_bytes()
+        image_id = images.put(data, connection=app_conn)
+
+        # A separate, ordinary ZeroBucket call (its own connection, no
+        # connection= passed) should NOT see this uncommitted row yet.
+        assert images.exists(image_id) is False
+
+        # But reading through the SAME transaction sees it fine.
+        result = images.get(image_id, connection=app_conn)
+        assert result.data == data
+
+        app_conn.rollback()
+        assert images.exists(image_id) is False
+    finally:
+        app_conn.close()

{zerobucket-0.2.0 → zerobucket-0.4.0}/tests/test_validation.py

@@ -10,9 +10,14 @@ from PIL import Image as PILImage
 from zerobucket.exceptions import (
     CorruptedImageError,
     ImageTooLargeError,
+    ImageValidationError,
     UnsupportedFormatError,
 )
-from zerobucket.validation import validate_image
+from zerobucket.validation import (
+    HEIF_SUPPORT_INSTALLED,
+    _looks_like_heic,
+    validate_image,
+)
 
 
 def _jpeg(size=(32, 32)) -> bytes:
@@ -22,6 +27,13 @@ def _jpeg(size=(32, 32)) -> bytes:
     return buf.getvalue()
 
 
+def _heic(size=(32, 32)) -> bytes:
+    img = PILImage.new("RGB", size, color=(10, 20, 30))
+    buf = io.BytesIO()
+    img.save(buf, format="HEIF", quality=90)
+    return buf.getvalue()
+
+
 def test_valid_jpeg_passes():
     data = _jpeg((100, 50))
     result = validate_image(data, max_bytes=10_000_000)
@@ -60,7 +72,9 @@ def test_empty_bytes_rejected():
 
 def test_random_bytes_rejected():
     with pytest.raises(CorruptedImageError):
-        validate_image(b"not an image, just some random bytes here" * 5, max_bytes=10_000_000)
+        validate_image(
+            b"not an image, just some random bytes here" * 5, max_bytes=10_000_000
+        )
 
 
 def test_truncated_image_rejected():
@@ -98,3 +112,48 @@ def test_decompression_bomb_guard():
     data = buf.getvalue()
     with pytest.raises((ImageTooLargeError, CorruptedImageError)):
         validate_image(data, max_bytes=10_000_000, max_pixels=1_000_000)
+
+
+@pytest.mark.skipif(not HEIF_SUPPORT_INSTALLED, reason="pillow-heif not installed")
+def test_valid_heic_passes():
+    data = _heic((100, 50))
+    result = validate_image(data, max_bytes=10_000_000)
+    assert result.mime_type == "image/heic"
+    assert result.width == 100
+    assert result.height == 50
+
+
+def test_looks_like_heic_detects_real_heic_magic_bytes():
+    """Sanity check for the sniffer itself, independent of whether
+    pillow-heif is installed -- this only inspects raw bytes."""
+    # A real HEIC ftyp box: box size (4 bytes) + 'ftyp' + 'heic' brand.
+    heic_like = b"\x00\x00\x00\x1cftypheic\x00\x00\x00\x00" + b"\x00" * 20
+    assert _looks_like_heic(heic_like) is True
+
+
+def test_looks_like_heic_rejects_non_heic_bytes():
+    assert _looks_like_heic(b"not an image at all, just text" * 3) is False
+    assert _looks_like_heic(_jpeg()) is False
+    assert _looks_like_heic(b"") is False
+    assert _looks_like_heic(b"short") is False
+
+
+def test_heic_without_optional_dependency_gives_actionable_error(monkeypatch):
+    """If pillow-heif isn't installed, a real HEIC upload should get a
+    clear "install this extra" message -- not a generic "corrupted image"
+    error that looks like the file itself is broken.
+
+    Simulated via monkeypatch rather than an actual separate environment,
+    since pillow-heif IS installed in the test/dev environment (it's in
+    the dev extra) -- this only forces the code path, it doesn't prove
+    the real uninstalled environment behaves identically. That was
+    verified manually in a clean venv during development; see the PR/
+    commit notes for that verification.
+    """
+    import zerobucket.validation as validation_module
+
+    monkeypatch.setattr(validation_module, "HEIF_SUPPORT_INSTALLED", False)
+
+    heic_bytes = b"\x00\x00\x00\x1cftypheic\x00\x00\x00\x00" + b"\x00" * 500
+    with pytest.raises(ImageValidationError, match=r"pip install zerobucket\[heic\]"):
+        validate_image(heic_bytes, max_bytes=10_000_000)