feat(firestore): add BSONBinary support (#18389)

This PR adds support for BSONBinary in the Firestore Python SDK.
BSONBinary` allows database applications to store subtyped binary data
payloads (such as UUIDs, MD5 hashes, or custom binary subtypes) in
Firestore documents.

* **`BSONBinary` Container Class**: Implements `BSONBinary(_BSONType)`
in `google.cloud.firestore_v1.bson`, wrapping binary payloads (`bytes`
or `bytearray`) and a 1-byte BSON subtype tag ($0 \le \text{subtype} \le
255$, defaulting to `0`).
* **Spec-Compliant Wire Serialization (`_to_map_value`)**:
 
- `subtype != 0` (subtyped binary): Serializes as `{"__binary__":
bytes([subtype]) + data}` (`map_value`).
* **Defensive Validation**:
- Raises `TypeError` for non-binary payloads or non-integer / boolean
subtype tags.
- Raises `ValueError` if `subtype` is outside the 1-byte range ($0 \le
\text{subtype} \le 255$).
* **SDK Exports & Post-Processing**: Exported `BSONBinary` in
`google.cloud.firestore` and `google.cloud.firestore_v1`, and updated
`.librarian/generator-input/client-post-processing/firestore-integration.yaml`.
* **Tests**: Added 14 atomic unit tests in `tests/unit/v1/test_bson.py`
and verified live sync and async write operations against Firestore
Enterprise DB.


Fixes b/562182261 🦕

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,68 @@ 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): A 1-byte BSON binary subtype tag (1 to 255).
+
+    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 (1 to 255).
+
+    Example:
+        >>> binary = BSONBinary(b"hello world", subtype=128)
+        >>> binary.data
+        b'hello world'
+        >>> binary.subtype
+        128
+    """
+
+    __slots__ = ("_data", "_subtype")
+
+    _MIN_SUBTYPE: int = 1
+    _MAX_SUBTYPE: int = 255
+
+    def __init__(self, data: Union[bytes, bytearray], subtype: int):
+        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._MIN_SUBTYPE <= subtype <= self._MAX_SUBTYPE):
+            raise ValueError(
+                f"BSONBinary subtype must be between {self._MIN_SUBTYPE} and {self._MAX_SUBTYPE}."
+            )
+        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 (1 to 255)."""
+        return self._subtype
+
+    def _to_map_value(self) -> Union[bytes, Dict[str, bytes]]:
+        """Returns representation for wire serialization."""
+        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,6 +49,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,
@@ -1292,6 +1293,7 @@ def test_bson_document_writes(client, cleanup, database):
         "min_key": BSONMinKey(),
         "max_key": BSONMaxKey(),
         "int32_val": BSONInt32(42),
+        "binary_val_sub128": BSONBinary(b"world", subtype=128),
     }
 
     doc_ref.set(bson_payload)
@@ -1303,6 +1305,7 @@ def test_bson_document_writes(client, cleanup, database):
         "min_key": {"__min__": None},
         "max_key": {"__max__": None},
         "int32_val": {"__int__": 42},
+        "binary_val_sub128": {"__binary__": b"\x80world"},
     }
 
 

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

@@ -52,6 +52,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 +1266,7 @@ async def test_async_bson_document_writes(client, cleanup, database):
         "min_key": BSONMinKey(),
         "max_key": BSONMaxKey(),
         "int32_val": BSONInt32(42),
+        "binary_val_sub128": BSONBinary(b"world", subtype=128),
     }
 
     await doc_ref.set(bson_payload)
@@ -1276,6 +1278,7 @@ async def test_async_bson_document_writes(client, cleanup, database):
         "min_key": {"__min__": None},
         "max_key": {"__max__": None},
         "int32_val": {"__int__": 42},
+        "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,80 @@ def test_bson_int32_copy():
 def test_bson_int32_pickle():
     val = BSONInt32(42)
     assert pickle.loads(pickle.dumps(val)) == val
+
+
+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"world", subtype=128)._to_map_value() == {
+        "__binary__": b"\x80world"
+    }
+
+
+def test_bson_binary_bytes_coercion():
+    assert bytes(BSONBinary(b"hello", subtype=1)) == b"hello"
+
+
+def test_bson_binary_repr():
+    assert (
+        repr(BSONBinary(b"world", subtype=128)) == "BSONBinary(b'world', subtype=128)"
+    )
+
+
+def test_bson_binary_boundaries():
+    bin_min = BSONBinary(b"test", subtype=1)
+    bin_max = BSONBinary(b"test", subtype=255)
+    assert bin_min.subtype == 1
+    assert bin_max.subtype == 255
+
+
+@pytest.mark.parametrize(
+    "data_input, subtype_input, exc_type, match_msg",
+    [
+        ("not bytes", 1, TypeError, "must be bytes or bytearray"),
+        (123, 1, TypeError, "must be bytes or bytearray"),
+        (None, 1, TypeError, "must be bytes or bytearray"),
+        (b"data", 256, ValueError, "must be between"),
+        (b"data", 0, 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", "1", 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=1)
+    bin2 = BSONBinary(b"abc", subtype=1)
+    bin3 = BSONBinary(b"abc", subtype=2)
+    bin4 = BSONBinary(b"xyz", subtype=1)
+    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=1)
+    bin2 = BSONBinary(b"abc", subtype=1)
+    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