zerobucket 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: zerobucket
-Version: 0.3.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
@@ -161,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.3.0 → zerobucket-0.4.0}/README.md

@@ -123,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.3.0 → zerobucket-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "zerobucket"
-version = "0.3.0"
+version = "0.4.0"
 description = "Database-native image storage. Your database. Your images. Zero buckets."
 readme = "README.md"
 license = "MIT"

{zerobucket-0.3.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.3.0"
+__version__ = "0.4.0"
 
 __all__ = [
     "ZeroBucket",

{zerobucket-0.3.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.3.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.3.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.
 
@@ -104,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)
 
@@ -148,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(
@@ -165,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(
@@ -180,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.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()