zerobucket 0.1.0__tar.gz

zerobucket-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+htmlcov/
+.coverage
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Environment / secrets -- never commit real credentials
+.env
+.env.*
+!.env.example
+
+# Editor/OS cruft
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Benchmark output (regenerate, don't version)
+benchmarks/results.csv
+benchmarks/test/retrieved*

zerobucket-0.1.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.5
+Name: zerobucket
+Version: 0.1.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
+Author-email: Kedar Ghadyalji <kedarghadyalji@gmail.com>
+License-Expression: MIT
+Keywords: bytea,image,postgresql,s3-alternative,storage
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Requires-Dist: pillow>=10.0
+Requires-Dist: psycopg-pool>=3.2
+Requires-Dist: psycopg[binary]>=3.1
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# zerobucket
+
+Database-native image storage. See the repository root README for full docs.

zerobucket-0.1.0/README.md

@@ -0,0 +1,3 @@
+# zerobucket
+
+Database-native image storage. See the repository root README for full docs.

zerobucket-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "zerobucket"
+version = "0.1.0"
+description = "Database-native image storage. Your database. Your images. Zero buckets."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Kedar Ghadyalji", email = "kedarghadyalji@gmail.com" }]
+keywords = ["image", "storage", "postgresql", "bytea", "s3-alternative"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Database",
+    "Topic :: Multimedia :: Graphics",
+]
+dependencies = [
+    "psycopg[binary]>=3.1",
+    "psycopg_pool>=3.2",
+    "Pillow>=10.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.6",
+    "mypy>=1.10",
+]
+
+[project.urls]
+Homepage = "https://github.com/KedarGhadyalji/ZeroBucket"
+Repository = "https://github.com/KedarGhadyalji/ZeroBucket"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zerobucket"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

zerobucket-0.1.0/src/zerobucket/__init__.py

@@ -0,0 +1,34 @@
+"""ZeroBucket: database-native image storage.
+
+    from zerobucket import ZeroBucket
+    images = ZeroBucket(database_url="postgresql://...")
+    image_id = images.put("avatar.jpg")
+    image = images.get(image_id)
+"""
+
+from .client import ZeroBucket
+from .exceptions import (
+    CorruptedImageError,
+    ImageNotFoundError,
+    ImageTooLargeError,
+    ImageValidationError,
+    StorageError,
+    UnsupportedFormatError,
+    ZeroBucketError,
+)
+from .types import Image, ImageMetadata
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ZeroBucket",
+    "Image",
+    "ImageMetadata",
+    "ZeroBucketError",
+    "ImageValidationError",
+    "ImageTooLargeError",
+    "UnsupportedFormatError",
+    "CorruptedImageError",
+    "ImageNotFoundError",
+    "StorageError",
+]

zerobucket-0.1.0/src/zerobucket/adapters/__init__.py

@@ -0,0 +1,9 @@
+from .base import StorageBackend, StoredRecord, StoredRecordMetadata
+from .postgres import PostgresBackend
+
+__all__ = [
+    "StorageBackend",
+    "StoredRecord",
+    "StoredRecordMetadata",
+    "PostgresBackend",
+]

zerobucket-0.1.0/src/zerobucket/adapters/base.py

@@ -0,0 +1,80 @@
+"""Storage backend interface.
+
+CRITICAL DESIGN RULE: implementations of this interface know nothing about
+images. They store and retrieve rows of bytes + metadata columns. All
+image-specific logic (validation, format detection, resizing) lives in
+zerobucket.client, above this layer.
+
+This separation is what makes a future object-storage backend a real
+drop-in replacement rather than a rewrite.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class StoredRecord:
+    """Raw record shape as persisted by a storage backend."""
+
+    id: str
+    data: bytes
+    mime_type: str
+    original_filename: str | None
+    size_bytes: int
+    width: int | None
+    height: int | None
+    checksum_sha256: str
+
+
+@dataclass(frozen=True, slots=True)
+class StoredRecordMetadata:
+    """Same as StoredRecord but without `data`, for cheap existence/info checks."""
+
+    id: str
+    mime_type: str
+    original_filename: str | None
+    size_bytes: int
+    width: int | None
+    height: int | None
+    checksum_sha256: str
+
+
+class StorageBackend(ABC):
+    """Abstract interface every ZeroBucket storage adapter must implement."""
+
+    @abstractmethod
+    def put(
+        self,
+        *,
+        data: bytes,
+        mime_type: str,
+        original_filename: str | None,
+        size_bytes: int,
+        width: int | None,
+        height: int | None,
+        checksum_sha256: str,
+    ) -> str:
+        """Persist a record and return its generated id."""
+
+    @abstractmethod
+    def get(self, image_id: str) -> 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:
+        """Fetch metadata only (no bytes), or None if it doesn't exist."""
+
+    @abstractmethod
+    def delete(self, image_id: str) -> 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:
+        """Return whether a record with this id exists."""
+
+    @abstractmethod
+    def close(self) -> None:
+        """Release underlying connections/resources."""

zerobucket-0.1.0/src/zerobucket/adapters/postgres.py

@@ -0,0 +1,172 @@
+"""PostgreSQL storage adapter.
+
+Stores image bytes directly in a BYTEA column. All queries are
+parameterized; nothing is ever built via string concatenation.
+"""
+
+from __future__ import annotations
+
+from psycopg_pool import ConnectionPool
+
+from ..exceptions import StorageError
+from .base import StorageBackend, StoredRecord, StoredRecordMetadata
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS zerobucket_images (
+    id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    data                BYTEA NOT NULL,
+    mime_type           TEXT NOT NULL,
+    original_filename   TEXT,
+    size_bytes          INTEGER NOT NULL,
+    width               INTEGER,
+    height              INTEGER,
+    checksum_sha256     CHAR(64) NOT NULL,
+    created_at          TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at          TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS idx_zerobucket_checksum ON zerobucket_images (checksum_sha256);
+CREATE INDEX IF NOT EXISTS idx_zerobucket_created_at ON zerobucket_images (created_at);
+"""
+
+_INSERT = """
+INSERT INTO zerobucket_images
+    (data, mime_type, original_filename, size_bytes, width, height, checksum_sha256)
+VALUES (%s, %s, %s, %s, %s, %s, %s)
+RETURNING id;
+"""
+
+_SELECT_FULL = """
+SELECT id, data, mime_type, original_filename, size_bytes, width, height, checksum_sha256
+FROM zerobucket_images
+WHERE id = %s;
+"""
+
+_SELECT_METADATA = """
+SELECT id, mime_type, original_filename, size_bytes, width, height, checksum_sha256
+FROM zerobucket_images
+WHERE id = %s;
+"""
+
+_DELETE = "DELETE FROM zerobucket_images WHERE id = %s;"
+
+_EXISTS = "SELECT 1 FROM zerobucket_images WHERE id = %s;"
+
+
+class PostgresBackend(StorageBackend):
+    """Storage backend for PostgreSQL using BYTEA columns.
+
+    Requires the pgcrypto extension (for gen_random_uuid()) on Postgres < 13.
+    Postgres 13+ has gen_random_uuid() built in.
+    """
+
+    def __init__(self, database_url: str, *, auto_migrate: bool = True) -> None:
+        try:
+            self._pool = ConnectionPool(
+                database_url, min_size=1, max_size=5, open=True, timeout=10
+            )
+        except Exception as exc:  # noqa: BLE001
+            raise StorageError(f"Could not connect to PostgreSQL: {exc}") from exc
+
+        if auto_migrate:
+            try:
+                self.migrate()
+            except Exception:
+                # Don't leak the pool's background worker threads if setup
+                # fails partway through -- close it before propagating so
+                # callers (and test runners) don't hang on shutdown.
+                self._pool.close()
+                raise
+
+    def migrate(self) -> None:
+        """Create the zerobucket_images table and indexes if they don't exist."""
+        try:
+            with self._pool.connection() as conn, conn.cursor() as cur:
+                cur.execute(_SCHEMA)
+        except Exception as exc:  # noqa: BLE001
+            raise StorageError(f"Migration failed: {exc}") from exc
+
+    def put(
+        self,
+        *,
+        data: bytes,
+        mime_type: str,
+        original_filename: str | None,
+        size_bytes: int,
+        width: int | None,
+        height: int | None,
+        checksum_sha256: str,
+    ) -> str:
+        try:
+            with self._pool.connection() as conn, conn.cursor() as cur:
+                params = (
+                    data,
+                    mime_type,
+                    original_filename,
+                    size_bytes,
+                    width,
+                    height,
+                    checksum_sha256,
+                )
+                cur.execute(_INSERT, params)
+                row = cur.fetchone()
+                return str(row[0])
+        except Exception as exc:  # noqa: BLE001
+            raise StorageError(f"Failed to store image: {exc}") from exc
+
+    def get(self, image_id: str) -> StoredRecord | None:
+        try:
+            with self._pool.connection() as conn, conn.cursor() as cur:
+                cur.execute(_SELECT_FULL, (image_id,))
+                row = cur.fetchone()
+        except Exception as exc:  # noqa: BLE001
+            raise StorageError(f"Failed to retrieve image: {exc}") from exc
+        if row is None:
+            return None
+        return StoredRecord(
+            id=str(row[0]),
+            data=bytes(row[1]),
+            mime_type=row[2],
+            original_filename=row[3],
+            size_bytes=row[4],
+            width=row[5],
+            height=row[6],
+            checksum_sha256=row[7],
+        )
+
+    def get_metadata(self, image_id: str) -> StoredRecordMetadata | None:
+        try:
+            with self._pool.connection() as conn, conn.cursor() as cur:
+                cur.execute(_SELECT_METADATA, (image_id,))
+                row = cur.fetchone()
+        except Exception as exc:  # noqa: BLE001
+            raise StorageError(f"Failed to retrieve image metadata: {exc}") from exc
+        if row is None:
+            return None
+        return StoredRecordMetadata(
+            id=str(row[0]),
+            mime_type=row[1],
+            original_filename=row[2],
+            size_bytes=row[3],
+            width=row[4],
+            height=row[5],
+            checksum_sha256=row[6],
+        )
+
+    def delete(self, image_id: str) -> bool:
+        try:
+            with self._pool.connection() as conn, conn.cursor() 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:
+        try:
+            with self._pool.connection() as conn, conn.cursor() as cur:
+                cur.execute(_EXISTS, (image_id,))
+                return cur.fetchone() is not None
+        except Exception as exc:  # noqa: BLE001
+            raise StorageError(f"Failed to check image existence: {exc}") from exc
+
+    def close(self) -> None:
+        self._pool.close()

zerobucket-0.1.0/src/zerobucket/client.py

@@ -0,0 +1,165 @@
+"""The public ZeroBucket SDK entry point.
+
+    from zerobucket import ZeroBucket
+    images = ZeroBucket(database_url="postgresql://...")
+    image_id = images.put("avatar.jpg")
+    image = images.get(image_id)
+
+The developer never needs to think about BYTEA, checksums, or connection
+pooling -- that's all handled below.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+from typing import BinaryIO, Union
+
+from .adapters.base import StorageBackend
+from .adapters.postgres import PostgresBackend
+from .exceptions import ImageNotFoundError
+from .types import Image, ImageMetadata
+from .validation import DEFAULT_MAX_PIXELS, SUPPORTED_FORMATS, validate_image
+
+# What put() accepts. Framework upload objects (e.g. Flask's FileStorage,
+# FastAPI's UploadFile) are duck-typed against BinaryIO via .read().
+ImageInput = Union[str, "os.PathLike[str]", bytes, BinaryIO]
+
+# 8 MiB. Chosen as a practical ceiling for "small app" images (see README
+# for rationale); pass max_bytes= to override per-instance.
+DEFAULT_MAX_BYTES = 8 * 1024 * 1024
+
+
+class ZeroBucket:
+    """Database-native image storage.
+
+    Args:
+        database_url: PostgreSQL connection string.
+        max_bytes: Maximum accepted image size in bytes. Defaults to 8 MiB.
+            ZeroBucket stores full images in a database column; it is not
+            designed for arbitrarily large files. See the README for why.
+        max_pixels: Decoded-pixel ceiling used to reject decompression
+            bombs, independent of compressed file size.
+        allowed_formats: Which image formats to accept. Defaults to
+            JPEG/PNG/WebP.
+        backend: Advanced -- inject a custom StorageBackend instead of
+            constructing a PostgresBackend from database_url.
+    """
+
+    def __init__(
+        self,
+        database_url: str | None = None,
+        *,
+        max_bytes: int = DEFAULT_MAX_BYTES,
+        max_pixels: int = DEFAULT_MAX_PIXELS,
+        allowed_formats: frozenset[str] = SUPPORTED_FORMATS,
+        backend: StorageBackend | None = None,
+    ) -> None:
+        if backend is not None:
+            self._backend = backend
+        elif database_url is not None:
+            self._backend = PostgresBackend(database_url)
+        else:
+            raise ValueError("Either database_url or backend must be provided")
+
+        self._max_bytes = max_bytes
+        self._max_pixels = max_pixels
+        self._allowed_formats = allowed_formats
+
+    def put(self, image: ImageInput, *, filename: str | None = None) -> str:
+        """Validate, process, and store an image. Returns its id.
+
+        Accepts a file path (str or PathLike), raw bytes, or any
+        file-like object with a .read() method.
+        """
+        data, resolved_filename = _read_image_input(image, filename)
+
+        validated = validate_image(
+            data,
+            max_bytes=self._max_bytes,
+            max_pixels=self._max_pixels,
+            allowed_formats=self._allowed_formats,
+        )
+        checksum = hashlib.sha256(data).hexdigest()
+
+        return self._backend.put(
+            data=data,
+            mime_type=validated.mime_type,
+            original_filename=resolved_filename,
+            size_bytes=validated.size_bytes,
+            width=validated.width,
+            height=validated.height,
+            checksum_sha256=checksum,
+        )
+
+    def get(self, image_id: str) -> Image:
+        """Retrieve a full image, including bytes. Raises ImageNotFoundError if missing."""
+        record = self._backend.get(image_id)
+        if record is None:
+            raise ImageNotFoundError(image_id)
+        return Image(
+            data=record.data,
+            mime_type=record.mime_type,
+            filename=record.original_filename,
+            size_bytes=record.size_bytes,
+            width=record.width,
+            height=record.height,
+            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)
+        if record is None:
+            raise ImageNotFoundError(image_id)
+        return ImageMetadata(
+            image_id=record.id,
+            mime_type=record.mime_type,
+            filename=record.original_filename,
+            size_bytes=record.size_bytes,
+            width=record.width,
+            height=record.height,
+            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 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)
+
+    def close(self) -> None:
+        """Release underlying database connections."""
+        self._backend.close()
+
+    def __enter__(self) -> ZeroBucket:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+
+def _read_image_input(
+    image: ImageInput, filename: str | None
+) -> tuple[bytes, str | None]:
+    """Normalize any accepted input type into (bytes, filename)."""
+    if isinstance(image, bytes):
+        return image, filename
+    if isinstance(image, (str, os.PathLike)):
+        path = Path(image)
+        data = path.read_bytes()
+        return data, filename or path.name
+    if hasattr(image, "read"):
+        data = image.read()
+        if isinstance(data, str):
+            raise TypeError("File-like object must be opened in binary mode")
+        raw_name = getattr(image, "filename", None) or getattr(image, "name", None)
+        resolved_filename = filename or (os.path.basename(raw_name) if raw_name else None)
+        return data, resolved_filename
+    raise TypeError(
+        f"Unsupported image input type: {type(image)!r}. "
+        "Expected a file path, bytes, or a file-like object with .read()."
+    )

zerobucket-0.1.0/src/zerobucket/exceptions.py

@@ -0,0 +1,54 @@
+"""Exception hierarchy for ZeroBucket.
+
+All exceptions inherit from ZeroBucketError so callers can catch broadly
+(`except ZeroBucketError`) or narrowly (`except ImageNotFoundError`).
+"""
+
+from __future__ import annotations
+
+
+class ZeroBucketError(Exception):
+    """Base class for all ZeroBucket exceptions."""
+
+
+class ImageValidationError(ZeroBucketError):
+    """Raised when an image fails validation (bad format, too large, corrupted, etc.)."""
+
+
+class ImageTooLargeError(ImageValidationError):
+    """Raised when an image exceeds the configured maximum size."""
+
+    def __init__(self, size_bytes: int, max_bytes: int) -> None:
+        self.size_bytes = size_bytes
+        self.max_bytes = max_bytes
+        super().__init__(
+            f"Image is {size_bytes} bytes, which exceeds the maximum of {max_bytes} bytes"
+        )
+
+
+class UnsupportedFormatError(ImageValidationError):
+    """Raised when an image's detected format is not in the allowed set."""
+
+    def __init__(self, detected_format: str | None, allowed: frozenset[str]) -> None:
+        self.detected_format = detected_format
+        self.allowed = allowed
+        super().__init__(
+            f"Detected format {detected_format!r} is not supported. "
+            f"Allowed formats: {sorted(allowed)}"
+        )
+
+
+class CorruptedImageError(ImageValidationError):
+    """Raised when image bytes cannot be decoded despite having a recognizable header."""
+
+
+class ImageNotFoundError(ZeroBucketError):
+    """Raised when get() or metadata() is called with an image_id that doesn't exist."""
+
+    def __init__(self, image_id: str) -> None:
+        self.image_id = image_id
+        super().__init__(f"No image found with id {image_id!r}")
+
+
+class StorageError(ZeroBucketError):
+    """Raised for underlying storage/database failures not covered above."""

zerobucket-0.1.0/src/zerobucket/types.py

@@ -0,0 +1,43 @@
+"""Public data types returned by the ZeroBucket SDK.
+
+These are the only shapes callers should depend on. Internal storage
+representation (BYTEA, column layout, etc.) is never exposed here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Image:
+    """A retrieved image, ready to be served or written to disk.
+
+    `data` is raw bytes -- never Base64. Serving it from a web framework
+    is just: Response(image.data, mimetype=image.mime_type)
+    """
+
+    data: bytes
+    mime_type: str
+    filename: str | None
+    size_bytes: int
+    width: int | None
+    height: int | None
+    checksum_sha256: str
+
+
+@dataclass(frozen=True, slots=True)
+class ImageMetadata:
+    """Metadata about a stored image, without the pixel data itself.
+
+    Useful for existence/info checks that shouldn't pull potentially
+    multi-megabyte blobs over the wire.
+    """
+
+    image_id: str
+    mime_type: str
+    filename: str | None
+    size_bytes: int
+    width: int | None
+    height: int | None
+    checksum_sha256: str

zerobucket-0.1.0/src/zerobucket/validation.py

@@ -0,0 +1,103 @@
+"""Image validation.
+
+Deliberately does NOT trust file extensions or client-supplied MIME types.
+The actual bytes are decoded with Pillow and the *detected* format is what
+gets validated and stored. This is the only source of truth.
+"""
+
+from __future__ import annotations
+
+import io
+from dataclasses import dataclass
+
+from PIL import Image as PILImage
+
+from .exceptions import (
+    CorruptedImageError,
+    ImageTooLargeError,
+    UnsupportedFormatError,
+)
+
+# Pillow format name -> canonical MIME type. Deliberately small allowlist;
+# extend this (and SUPPORTED_FORMATS) to add formats, never bypass it.
+_FORMAT_TO_MIME = {
+    "JPEG": "image/jpeg",
+    "PNG": "image/png",
+    "WEBP": "image/webp",
+}
+
+SUPPORTED_FORMATS = frozenset(_FORMAT_TO_MIME)
+
+# Guard against decompression bombs: reject images that would decode to
+# more than this many pixels, regardless of how small the compressed
+# bytes are. ~89 megapixels ~= a 12000x7400 image.
+DEFAULT_MAX_PIXELS = 89_000_000
+
+
+@dataclass(frozen=True, slots=True)
+class ValidatedImage:
+    """Result of successful validation: everything derived from the bytes."""
+
+    mime_type: str
+    width: int
+    height: int
+    size_bytes: int
+
+
+def validate_image(
+    data: bytes,
+    *,
+    max_bytes: int,
+    max_pixels: int = DEFAULT_MAX_PIXELS,
+    allowed_formats: frozenset[str] = SUPPORTED_FORMATS,
+) -> ValidatedImage:
+    """Validate raw image bytes and return derived metadata.
+
+    Raises ImageTooLargeError, UnsupportedFormatError, or CorruptedImageError.
+    Never raises for reasons unrelated to the image itself.
+    """
+    size_bytes = len(data)
+    if size_bytes > max_bytes:
+        raise ImageTooLargeError(size_bytes, max_bytes)
+    if size_bytes == 0:
+        raise CorruptedImageError("Image data is empty")
+
+    # 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.
+    original_max_pixels = PILImage.MAX_IMAGE_PIXELS
+    try:
+        PILImage.MAX_IMAGE_PIXELS = max_pixels
+        try:
+            with PILImage.open(io.BytesIO(data)) as img:
+                detected_format = img.format
+                if detected_format not in allowed_formats:
+                    raise UnsupportedFormatError(detected_format, allowed_formats)
+                width, height = img.size
+                # .verify() only checks structural integrity; it does not
+                # decode pixel data (and Pillow requires reopening after
+                # calling it). Force a full pixel decode below to catch
+                # truncated/corrupted image bodies, not just bad headers.
+        except UnsupportedFormatError:
+            raise
+        except PILImage.DecompressionBombError as exc:
+            raise ImageTooLargeError(size_bytes, max_bytes) from exc
+        except Exception as exc:  # noqa: BLE001 - Pillow raises many exception types
+            raise CorruptedImageError(f"Could not decode image: {exc}") from exc
+
+        # Force full pixel decode to catch truncated image bodies that pass
+        # header parsing but fail partway through the data.
+        try:
+            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
+    finally:
+        PILImage.MAX_IMAGE_PIXELS = original_max_pixels
+
+    return ValidatedImage(
+        mime_type=_FORMAT_TO_MIME[detected_format],
+        width=width,
+        height=height,
+        size_bytes=size_bytes,
+    )

zerobucket-0.1.0/tests/conftest.py

@@ -0,0 +1,75 @@
+"""Shared pytest fixtures.
+
+Integration tests require a real PostgreSQL instance. Set
+ZEROBUCKET_TEST_DATABASE_URL to point at a throwaway database, e.g.:
+
+    export ZEROBUCKET_TEST_DATABASE_URL=postgresql://postgres:postgres@localhost:5432/zerobucket_test
+
+Tests truncate the zerobucket_images table between runs rather than
+dropping the database, so they're safe to run repeatedly.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+
+import pytest
+from PIL import Image as PILImage
+
+from zerobucket import ZeroBucket
+from zerobucket.adapters.postgres import PostgresBackend
+
+TEST_DATABASE_URL = os.environ.get(
+    "ZEROBUCKET_TEST_DATABASE_URL",
+    "postgresql://postgres:postgres@localhost:5432/zerobucket_test",
+)
+
+
+def _make_image_bytes(*, size=(64, 48), color=(255, 0, 0), fmt="JPEG") -> bytes:
+    img = PILImage.new("RGB", size, color=color)
+    buf = io.BytesIO()
+    img.save(buf, format=fmt)
+    return buf.getvalue()
+
+
+@pytest.fixture(scope="session")
+def _db_available():
+    """Skip all integration tests cleanly if no test database is reachable."""
+    try:
+        backend = PostgresBackend(TEST_DATABASE_URL)
+        backend.close()
+    except Exception as exc:  # noqa: BLE001
+        pytest.skip(f"No reachable test database ({TEST_DATABASE_URL}): {exc}")
+
+
+@pytest.fixture
+def images(_db_available):
+    """A ZeroBucket instance backed by a clean test table for each test."""
+    zb = ZeroBucket(database_url=TEST_DATABASE_URL)
+    # Ensure a clean slate per test rather than per session.
+    with zb._backend._pool.connection() as conn, conn.cursor() as cur:  # noqa: SLF001
+        cur.execute("TRUNCATE TABLE zerobucket_images;")
+    yield zb
+    zb.close()
+
+
+@pytest.fixture
+def jpeg_bytes() -> bytes:
+    return _make_image_bytes(fmt="JPEG")
+
+
+@pytest.fixture
+def png_bytes() -> bytes:
+    return _make_image_bytes(fmt="PNG")
+
+
+@pytest.fixture
+def webp_bytes() -> bytes:
+    return _make_image_bytes(fmt="WEBP")
+
+
+@pytest.fixture
+def make_image_bytes():
+    """Factory fixture for tests that need custom size/color/format."""
+    return _make_image_bytes

zerobucket-0.1.0/tests/test_client.py

@@ -0,0 +1,181 @@
+"""Integration tests against a real PostgreSQL database.
+
+Requires ZEROBUCKET_TEST_DATABASE_URL (see conftest.py). Tests are skipped
+automatically if no database is reachable.
+"""
+
+from __future__ import annotations
+
+import io
+
+import pytest
+
+from zerobucket import ZeroBucket
+from zerobucket.exceptions import (
+    ImageNotFoundError,
+    ImageTooLargeError,
+    UnsupportedFormatError,
+)
+
+
+def test_put_and_get_round_trip(images, jpeg_bytes):
+    image_id = images.put(jpeg_bytes, filename="photo.jpg")
+    result = images.get(image_id)
+
+    assert result.data == jpeg_bytes
+    assert result.mime_type == "image/jpeg"
+    assert result.filename == "photo.jpg"
+    assert result.width == 64
+    assert result.height == 48
+    assert result.size_bytes == len(jpeg_bytes)
+    assert len(result.checksum_sha256) == 64
+
+
+def test_put_from_file_path(images, tmp_path, jpeg_bytes):
+    path = tmp_path / "avatar.jpg"
+    path.write_bytes(jpeg_bytes)
+
+    image_id = images.put(str(path))
+    result = images.get(image_id)
+
+    assert result.data == jpeg_bytes
+    assert result.filename == "avatar.jpg"
+
+
+def test_put_from_pathlib_path(images, tmp_path, jpeg_bytes):
+    path = tmp_path / "avatar2.jpg"
+    path.write_bytes(jpeg_bytes)
+
+    image_id = images.put(path)
+    result = images.get(image_id)
+
+    assert result.data == jpeg_bytes
+
+
+def test_put_from_file_like_object(images, jpeg_bytes):
+    file_obj = io.BytesIO(jpeg_bytes)
+    file_obj.name = "upload.jpg"
+
+    image_id = images.put(file_obj)
+    result = images.get(image_id)
+
+    assert result.data == jpeg_bytes
+    assert result.filename == "upload.jpg"
+
+
+def test_explicit_filename_overrides_inferred_one(images, tmp_path, jpeg_bytes):
+    path = tmp_path / "original_name.jpg"
+    path.write_bytes(jpeg_bytes)
+
+    image_id = images.put(str(path), filename="renamed.jpg")
+    result = images.get(image_id)
+
+    assert result.filename == "renamed.jpg"
+
+
+def test_different_formats_all_supported(images, jpeg_bytes, png_bytes, webp_bytes):
+    jpeg_id = images.put(jpeg_bytes)
+    png_id = images.put(png_bytes)
+    webp_id = images.put(webp_bytes)
+
+    assert images.get(jpeg_id).mime_type == "image/jpeg"
+    assert images.get(png_id).mime_type == "image/png"
+    assert images.get(webp_id).mime_type == "image/webp"
+
+
+def test_get_missing_image_raises(images):
+    fake_id = "00000000-0000-0000-0000-000000000000"
+    with pytest.raises(ImageNotFoundError):
+        images.get(fake_id)
+
+
+def test_metadata_missing_image_raises(images):
+    fake_id = "00000000-0000-0000-0000-000000000000"
+    with pytest.raises(ImageNotFoundError):
+        images.metadata(fake_id)
+
+
+def test_metadata_matches_get_but_excludes_data(images, jpeg_bytes):
+    image_id = images.put(jpeg_bytes, filename="a.jpg")
+    full = images.get(image_id)
+    meta = images.metadata(image_id)
+
+    assert meta.image_id == image_id
+    assert meta.mime_type == full.mime_type
+    assert meta.filename == full.filename
+    assert meta.size_bytes == full.size_bytes
+    assert meta.width == full.width
+    assert meta.height == full.height
+    assert meta.checksum_sha256 == full.checksum_sha256
+    assert not hasattr(meta, "data")
+
+
+def test_exists_true_for_stored_image(images, jpeg_bytes):
+    image_id = images.put(jpeg_bytes)
+    assert images.exists(image_id) is True
+
+
+def test_exists_false_for_missing_image(images):
+    assert images.exists("00000000-0000-0000-0000-000000000000") is False
+
+
+def test_delete_removes_image(images, jpeg_bytes):
+    image_id = images.put(jpeg_bytes)
+    assert images.delete(image_id) is True
+    assert images.exists(image_id) is False
+    with pytest.raises(ImageNotFoundError):
+        images.get(image_id)
+
+
+def test_delete_missing_image_returns_false(images):
+    assert images.delete("00000000-0000-0000-0000-000000000000") is False
+
+
+def test_uploading_same_image_twice_creates_two_records(images, jpeg_bytes):
+    """Dedup is explicitly deferred (see architecture notes) -- verify current,
+    documented behavior: duplicate uploads create separate rows with matching
+    checksums, rather than silently merging or erroring."""
+    id_a = images.put(jpeg_bytes)
+    id_b = images.put(jpeg_bytes)
+
+    assert id_a != id_b
+    assert images.get(id_a).checksum_sha256 == images.get(id_b).checksum_sha256
+
+
+def test_size_limit_enforced(_db_available, make_image_bytes):
+    from tests.conftest import TEST_DATABASE_URL
+
+    small_images = ZeroBucket(database_url=TEST_DATABASE_URL, max_bytes=200)
+    try:
+        data = make_image_bytes(size=(200, 200))
+        with pytest.raises(ImageTooLargeError):
+            small_images.put(data)
+    finally:
+        small_images.close()
+
+
+def test_unsupported_format_rejected(images):
+    with pytest.raises(UnsupportedFormatError):
+        # Minimal valid GIF header + trailer.
+        gif = bytes.fromhex(
+            "47494638396101000100800000000000ffffff21f90401000000002c00000000010001000002024401003b"
+        )
+        images.put(gif, filename="test.gif")
+
+
+def test_concurrent_puts_all_succeed(images, make_image_bytes):
+    """Basic concurrency smoke test: N images uploaded via threads all round-trip correctly."""
+    import concurrent.futures
+
+    payloads = [make_image_bytes(color=(i % 255, 0, 0)) for i in range(10)]
+
+    def upload(data: bytes) -> tuple[str, bytes]:
+        return images.put(data), data
+
+    with concurrent.futures.ThreadPoolExecutor(max_workers=5) as pool:
+        results = list(pool.map(upload, payloads))
+
+    ids = [r[0] for r in results]
+    assert len(set(ids)) == len(ids)  # all ids unique
+    for image_id, original_data in results:
+        assert images.get(image_id).data == original_data

zerobucket-0.1.0/tests/test_errors.py

@@ -0,0 +1,27 @@
+"""Tests for error handling that don't require a healthy database connection."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import pytest
+
+from zerobucket import ZeroBucket
+from zerobucket.client import ZeroBucket as ZB
+from zerobucket.exceptions import StorageError
+
+
+def test_unreachable_database_raises_storage_error():
+    with pytest.raises(StorageError):
+        ZeroBucket(database_url="postgresql://baduser:badpass@localhost:1/nonexistent_db")
+
+
+def test_zerobucket_requires_database_url_or_backend():
+    with pytest.raises(ValueError):
+        ZeroBucket()
+
+
+def test_put_rejects_unsupported_input_type():
+    zb = ZB(backend=MagicMock())
+    with pytest.raises(TypeError):
+        zb.put(12345)  # not a path, bytes, or file-like object

zerobucket-0.1.0/tests/test_validation.py

@@ -0,0 +1,100 @@
+"""Unit tests for image validation. No database required."""
+
+from __future__ import annotations
+
+import io
+
+import pytest
+from PIL import Image as PILImage
+
+from zerobucket.exceptions import (
+    CorruptedImageError,
+    ImageTooLargeError,
+    UnsupportedFormatError,
+)
+from zerobucket.validation import validate_image
+
+
+def _jpeg(size=(32, 32)) -> bytes:
+    img = PILImage.new("RGB", size, color=(10, 20, 30))
+    buf = io.BytesIO()
+    img.save(buf, format="JPEG")
+    return buf.getvalue()
+
+
+def test_valid_jpeg_passes():
+    data = _jpeg((100, 50))
+    result = validate_image(data, max_bytes=10_000_000)
+    assert result.mime_type == "image/jpeg"
+    assert result.width == 100
+    assert result.height == 50
+    assert result.size_bytes == len(data)
+
+
+def test_valid_png_passes():
+    img = PILImage.new("RGB", (10, 10))
+    buf = io.BytesIO()
+    img.save(buf, format="PNG")
+    result = validate_image(buf.getvalue(), max_bytes=10_000_000)
+    assert result.mime_type == "image/png"
+
+
+def test_valid_webp_passes():
+    img = PILImage.new("RGB", (10, 10))
+    buf = io.BytesIO()
+    img.save(buf, format="WEBP")
+    result = validate_image(buf.getvalue(), max_bytes=10_000_000)
+    assert result.mime_type == "image/webp"
+
+
+def test_oversized_image_rejected():
+    data = _jpeg((500, 500))
+    with pytest.raises(ImageTooLargeError):
+        validate_image(data, max_bytes=10)
+
+
+def test_empty_bytes_rejected():
+    with pytest.raises(CorruptedImageError):
+        validate_image(b"", max_bytes=10_000_000)
+
+
+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)
+
+
+def test_truncated_image_rejected():
+    data = _jpeg((200, 200))
+    truncated = data[: len(data) // 3]
+    with pytest.raises(CorruptedImageError):
+        validate_image(truncated, max_bytes=10_000_000)
+
+
+def test_gif_rejected_as_unsupported_format():
+    img = PILImage.new("RGB", (10, 10))
+    buf = io.BytesIO()
+    img.save(buf, format="GIF")
+    with pytest.raises(UnsupportedFormatError):
+        validate_image(buf.getvalue(), max_bytes=10_000_000)
+
+
+def test_does_not_trust_fake_extension_only_content():
+    """A PNG's magic bytes determine its type, regardless of what a caller might claim."""
+    img = PILImage.new("RGB", (10, 10))
+    buf = io.BytesIO()
+    img.save(buf, format="PNG")
+    data = buf.getvalue()
+    # Even though nothing here claims "this is a .jpg", validate_image must
+    # detect PNG from content, not trust any external hint.
+    result = validate_image(data, max_bytes=10_000_000)
+    assert result.mime_type == "image/png"
+
+
+def test_decompression_bomb_guard():
+    """A tiny compressed image that claims an enormous pixel count is rejected."""
+    img = PILImage.new("RGB", (20000, 20000), color=(1, 1, 1))
+    buf = io.BytesIO()
+    img.save(buf, format="PNG", compress_level=9)
+    data = buf.getvalue()
+    with pytest.raises((ImageTooLargeError, CorruptedImageError)):
+        validate_image(data, max_bytes=10_000_000, max_pixels=1_000_000)