zerobucket 0.2.0__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: zerobucket
-Version: 0.2.0
+Version: 0.3.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

{zerobucket-0.2.0 → zerobucket-0.3.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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "zerobucket"
-version = "0.2.0"
+version = "0.3.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.3.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.3.0"
 
 __all__ = [
     "ZeroBucket",

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

@@ -93,7 +93,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

{zerobucket-0.2.0 → zerobucket-0.3.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.3.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.3.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.2.0 → zerobucket-0.3.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)