feat(firestore): add BSONBinary support

Author: ohmayr

.librarian/generator-input/client-post-processing/firestore-integration.yaml

@@ -70,6 +70,7 @@ replacements:
       from google.cloud.firestore_v1.base_query import And, FieldFilter, Or
       from google.cloud.firestore_v1.batch import WriteBatch
       from google.cloud.firestore_v1.bson import (
+          BSONBinary,
           BSONInt32,
           BSONMaxKey,
           BSONMinKey,
@@ -176,6 +177,7 @@ replacements:
           "async_transactional",
           "AsyncTransaction",
           "AsyncWriteBatch",
+          "BSONBinary",
           "BSONInt32",
           "BSONMaxKey",
           "BSONMinKey",
@@ -252,6 +254,7 @@ replacements:
           AsyncQuery,
           AsyncTransaction,
           AsyncWriteBatch,
+          BSONBinary,
           BSONInt32,
           BSONMaxKey,
           BSONMinKey,
@@ -313,6 +316,7 @@ replacements:
           "async_transactional",
           "AsyncTransaction",
           "AsyncWriteBatch",
+          "BSONBinary",
           "BSONInt32",
           "BSONMaxKey",
           "BSONMinKey",

packages/google-cloud-firestore/google/cloud/firestore/__init__.py

@@ -35,6 +35,7 @@
     AsyncQuery,
     AsyncTransaction,
     AsyncWriteBatch,
+    BSONBinary,
     BSONInt32,
     BSONMaxKey,
     BSONMinKey,
@@ -96,6 +97,7 @@
     "async_transactional",
     "AsyncTransaction",
     "AsyncWriteBatch",
+    "BSONBinary",
     "BSONInt32",
     "BSONMaxKey",
     "BSONMinKey",

packages/google-cloud-firestore/google/cloud/firestore_v1/__init__.py

@@ -47,6 +47,7 @@
 from google.cloud.firestore_v1.base_query import And, FieldFilter, Or
 from google.cloud.firestore_v1.batch import WriteBatch
 from google.cloud.firestore_v1.bson import (
+    BSONBinary,
     BSONInt32,
     BSONMaxKey,
     BSONMinKey,
@@ -153,6 +154,7 @@
     "async_transactional",
     "AsyncTransaction",
     "AsyncWriteBatch",
+    "BSONBinary",
     "BSONInt32",
     "BSONMaxKey",
     "BSONMinKey",

packages/google-cloud-firestore/google/cloud/firestore_v1/bson.py

@@ -33,6 +33,7 @@
     "BSONMinKey",
     "BSONMaxKey",
     "BSONInt32",
+    "BSONBinary",
 ]
 
 _OBJECT_ID_BYTES_LEN = 12
@@ -214,3 +215,75 @@ def __eq__(self, other: Any) -> bool:
 
     def __hash__(self) -> int:
         return hash((type(self), self._value))
+
+
+class BSONBinary(_BSONType):
+    """Represents a BSON binary data container with a subtype for Firestore.
+
+    Args:
+        data (Union[bytes, bytearray]): The binary byte payload.
+        subtype (int, optional): A 1-byte BSON binary subtype tag (0 to 255).
+            Defaults to 0 (generic binary).
+
+    Raises:
+        TypeError: If data is not bytes/bytearray or subtype is not an integer/is a boolean.
+        ValueError: If subtype is outside the 1-byte range (0 to 255).
+
+    Example:
+        >>> binary = BSONBinary(b"hello world", subtype=0)
+        >>> binary.data
+        b'hello world'
+        >>> binary.subtype
+        0
+    """
+
+    __slots__ = ("_data", "_subtype")
+
+    _SUBTYPE_MIN: int = 0
+    _SUBTYPE_MAX: int = 255
+
+    def __init__(self, data: Union[bytes, bytearray], subtype: int = 0):
+        if not isinstance(data, (bytes, bytearray)):
+            raise TypeError("BSONBinary data must be bytes or bytearray.")
+        if isinstance(subtype, bool) or not isinstance(subtype, int):
+            raise TypeError("BSONBinary subtype must be an int.")
+        if not (self._SUBTYPE_MIN <= subtype <= self._SUBTYPE_MAX):
+            raise ValueError(
+                f"BSONBinary subtype must be between {self._SUBTYPE_MIN} and {self._SUBTYPE_MAX}."
+            )
+        self._data: bytes = bytes(data)
+        self._subtype: int = subtype
+
+    @property
+    def data(self) -> bytes:
+        """bytes: The binary byte payload."""
+        return self._data
+
+    @property
+    def subtype(self) -> int:
+        """int: The BSON binary subtype tag (0 to 255)."""
+        return self._subtype
+
+    def _to_map_value(self) -> Union[bytes, Dict[str, bytes]]:
+        """Returns representation for wire serialization.
+
+        If subtype is 0 (generic binary), returns raw bytes.
+        If subtype is non-zero, returns map dictionary representation.
+        """
+        if self._subtype == 0:
+            return self._data
+        return {"__binary__": bytes([self._subtype]) + self._data}
+
+    def __repr__(self) -> str:
+        return f"BSONBinary({self._data!r}, subtype={self._subtype})"
+
+    def __bytes__(self) -> bytes:
+        return self._data
+
+    def __eq__(self, other: Any) -> bool:
+        if isinstance(other, BSONBinary):
+            return self._data == other._data and self._subtype == other._subtype
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash((type(self), self._data, self._subtype))

packages/google-cloud-firestore/tests/system/test_system.py

@@ -49,14 +49,14 @@
 from google.cloud.firestore_v1.base_query import And, FieldFilter, Or
 from google.cloud.firestore_v1.base_vector_query import DistanceMeasure
 from google.cloud.firestore_v1.bson import (
+    BSONBinary,
     BSONInt32,
     BSONMaxKey,
     BSONMinKey,
     BSONObjectId,
 )
 from google.cloud.firestore_v1.vector import Vector
 
-
 def _get_credentials_and_project():
     if FIRESTORE_EMULATOR:
         credentials = EMULATOR_CREDS
@@ -1292,6 +1292,8 @@ def test_bson_document_writes(client, cleanup, database):
         "min_key": BSONMinKey(),
         "max_key": BSONMaxKey(),
         "int32_val": BSONInt32(42),
+        "binary_val_sub0": BSONBinary(b"hello", subtype=0),
+        "binary_val_sub128": BSONBinary(b"world", subtype=128),
     }
 
     doc_ref.set(bson_payload)
@@ -1303,6 +1305,8 @@ def test_bson_document_writes(client, cleanup, database):
         "min_key": {"__min__": None},
         "max_key": {"__max__": None},
         "int32_val": {"__int__": 42},
+        "binary_val_sub0": b"hello",
+        "binary_val_sub128": {"__binary__": b"\x80world"},
     }
 
 

packages/google-cloud-firestore/tests/system/test_system_async.py

@@ -32,6 +32,13 @@
     NotFound,
 )
 from google.cloud._helpers import _datetime_to_pb_timestamp
+from google.cloud.firestore_v1.bson import (
+    BSONBinary,
+    BSONInt32,
+    BSONMaxKey,
+    BSONMinKey,
+    BSONObjectId,
+)
 from google.oauth2 import service_account
 from test__helpers import (
     EMULATOR_CREDS,
@@ -52,6 +59,7 @@
 from google.cloud.firestore_v1.base_query import And, FieldFilter, Or
 from google.cloud.firestore_v1.base_vector_query import DistanceMeasure
 from google.cloud.firestore_v1.bson import (
+    BSONBinary,
     BSONInt32,
     BSONMaxKey,
     BSONMinKey,
@@ -1265,6 +1273,8 @@ async def test_async_bson_document_writes(client, cleanup, database):
         "min_key": BSONMinKey(),
         "max_key": BSONMaxKey(),
         "int32_val": BSONInt32(42),
+        "binary_val_sub0": BSONBinary(b"hello", subtype=0),
+        "binary_val_sub128": BSONBinary(b"world", subtype=128),
     }
 
     await doc_ref.set(bson_payload)
@@ -1276,6 +1286,8 @@ async def test_async_bson_document_writes(client, cleanup, database):
         "min_key": {"__min__": None},
         "max_key": {"__max__": None},
         "int32_val": {"__int__": 42},
+        "binary_val_sub0": b"hello",
+        "binary_val_sub128": {"__binary__": b"\x80world"},
     }
 
 

packages/google-cloud-firestore/tests/unit/v1/test_bson.py

@@ -21,6 +21,7 @@
 import pytest
 
 from google.cloud.firestore_v1.bson import (
+    BSONBinary,
     BSONInt32,
     BSONMaxKey,
     BSONMinKey,
@@ -267,3 +268,87 @@ def test_bson_int32_copy():
 def test_bson_int32_pickle():
     val = BSONInt32(42)
     assert pickle.loads(pickle.dumps(val)) == val
+
+
+def test_bson_binary_default_subtype():
+    val = BSONBinary(b"hello")
+    assert val.data == b"hello"
+    assert val.subtype == 0
+
+
+def test_bson_binary_custom_subtype():
+    val = BSONBinary(bytearray(b"world"), subtype=128)
+    assert val.data == b"world"
+    assert val.subtype == 128
+
+
+def test_bson_binary_to_map_value():
+    assert BSONBinary(b"hello", subtype=0)._to_map_value() == b"hello"
+    assert BSONBinary(b"world", subtype=128)._to_map_value() == {
+        "__binary__": b"\x80world"
+    }
+
+
+def test_bson_binary_bytes_coercion():
+    assert bytes(BSONBinary(b"hello")) == b"hello"
+
+
+def test_bson_binary_repr():
+    assert repr(BSONBinary(b"hello", subtype=0)) == "BSONBinary(b'hello', subtype=0)"
+    assert (
+        repr(BSONBinary(b"world", subtype=128)) == "BSONBinary(b'world', subtype=128)"
+    )
+
+
+def test_bson_binary_boundaries():
+    bin_min = BSONBinary(b"test", subtype=0)
+    bin_max = BSONBinary(b"test", subtype=255)
+    assert bin_min.subtype == 0
+    assert bin_max.subtype == 255
+
+
+@pytest.mark.parametrize(
+    "data_input, subtype_input, exc_type, match_msg",
+    [
+        ("not bytes", 0, TypeError, "must be bytes or bytearray"),
+        (123, 0, TypeError, "must be bytes or bytearray"),
+        (None, 0, TypeError, "must be bytes or bytearray"),
+        (b"data", 256, ValueError, "must be between"),
+        (b"data", -1, ValueError, "must be between"),
+        (b"data", True, TypeError, "subtype must be an int"),
+        (b"data", False, TypeError, "subtype must be an int"),
+        (b"data", "0", TypeError, "subtype must be an int"),
+    ],
+)
+def test_bson_binary_invalid_inputs(data_input, subtype_input, exc_type, match_msg):
+    with pytest.raises(exc_type, match=match_msg):
+        BSONBinary(data_input, subtype=subtype_input)
+
+
+def test_bson_binary_equality():
+    bin1 = BSONBinary(b"abc", subtype=0)
+    bin2 = BSONBinary(b"abc", subtype=0)
+    bin3 = BSONBinary(b"abc", subtype=1)
+    bin4 = BSONBinary(b"xyz", subtype=0)
+    assert bin1 == bin2
+    assert bin1 != bin3
+    assert bin1 != bin4
+    assert bin1 != b"abc"
+
+
+def test_bson_binary_hash_and_dict_key():
+    bin1 = BSONBinary(b"abc", subtype=0)
+    bin2 = BSONBinary(b"abc", subtype=0)
+    assert hash(bin1) == hash(bin2)
+    assert len({bin1, bin2}) == 1
+
+
+def test_bson_binary_copy():
+    val = BSONBinary(b"hello", subtype=5)
+    assert copy.copy(val) == val
+    assert copy.deepcopy(val) == val
+
+
+def test_bson_binary_pickle():
+    val = BSONBinary(b"hello", subtype=5)
+    assert pickle.loads(pickle.dumps(val)) == val