feat(firestore): add BSONInt32 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 (
+          BSONInt32,
           BSONMaxKey,
           BSONMinKey,
           BSONObjectId,
@@ -175,6 +176,7 @@ replacements:
           "async_transactional",
           "AsyncTransaction",
           "AsyncWriteBatch",
+          "BSONInt32",
           "BSONMaxKey",
           "BSONMinKey",
           "BSONObjectId",
@@ -250,6 +252,7 @@ replacements:
           AsyncQuery,
           AsyncTransaction,
           AsyncWriteBatch,
+          BSONInt32,
           BSONMaxKey,
           BSONMinKey,
           BSONObjectId,
@@ -310,6 +313,7 @@ replacements:
           "async_transactional",
           "AsyncTransaction",
           "AsyncWriteBatch",
+          "BSONInt32",
           "BSONMaxKey",
           "BSONMinKey",
           "BSONObjectId",

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

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

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 (
+    BSONInt32,
     BSONMaxKey,
     BSONMinKey,
     BSONObjectId,
@@ -152,6 +153,7 @@
     "async_transactional",
     "AsyncTransaction",
     "AsyncWriteBatch",
+    "BSONInt32",
     "BSONMaxKey",
     "BSONMinKey",
     "BSONObjectId",

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

@@ -32,6 +32,7 @@
     "BSONObjectId",
     "BSONMinKey",
     "BSONMaxKey",
+    "BSONInt32",
 ]
 
 _OBJECT_ID_BYTES_LEN = 12
@@ -156,3 +157,60 @@ def __eq__(self, other: Any) -> bool:
 
     def __hash__(self) -> int:
         return hash(type(self))
+
+
+class BSONInt32(_BSONType):
+    """Represents a 32-bit signed integer value container for Firestore BSON.
+
+    Args:
+        value (int): A 32-bit signed integer value.
+
+    Raises:
+        TypeError: If value is not an integer or is a boolean.
+        ValueError: If value is outside the 32-bit signed range (-2147483648 to 2147483647).
+
+    Example:
+        >>> int_val = BSONInt32(42)
+        >>> int_val.value
+        42
+    """
+
+    __slots__ = ("_value",)
+
+    _MIN_VALUE: int = -(1 << 31)
+    _MAX_VALUE: int = (1 << 31) - 1
+
+    def __init__(self, value: int):
+        if isinstance(value, bool) or not isinstance(value, int):
+            raise TypeError("BSONInt32 requires an int.")
+        if not (self._MIN_VALUE <= value <= self._MAX_VALUE):
+            raise ValueError(
+                f"BSONInt32 value must be between {self._MIN_VALUE} and {self._MAX_VALUE}."
+            )
+        self._value: int = value
+
+    @property
+    def value(self) -> int:
+        """int: The 32-bit signed integer value."""
+        return self._value
+
+    def _to_map_value(self) -> Dict[str, int]:
+        """Returns map dictionary representation for wire serialization."""
+        return {"__int__": self._value}
+
+    def __repr__(self) -> str:
+        return f"BSONInt32({self._value})"
+
+    def __str__(self) -> str:
+        return str(self._value)
+
+    def __int__(self) -> int:
+        return self._value
+
+    def __eq__(self, other: Any) -> bool:
+        if isinstance(other, BSONInt32):
+            return self._value == other._value
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash((type(self), self._value))

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

@@ -48,7 +48,12 @@
 from google.cloud import firestore_v1 as firestore
 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 BSONMaxKey, BSONMinKey, BSONObjectId
+from google.cloud.firestore_v1.bson import (
+    BSONInt32,
+    BSONMaxKey,
+    BSONMinKey,
+    BSONObjectId,
+)
 from google.cloud.firestore_v1.vector import Vector
 
 
@@ -1286,6 +1291,7 @@ def test_bson_document_writes(client, cleanup, database):
         "user_id": BSONObjectId("507f191e810c19729de860ea"),
         "min_key": BSONMinKey(),
         "max_key": BSONMaxKey(),
+        "int32_val": BSONInt32(42),
     }
 
     doc_ref.set(bson_payload)
@@ -1296,6 +1302,7 @@ def test_bson_document_writes(client, cleanup, database):
         "user_id": {"__oid__": "507f191e810c19729de860ea"},
         "min_key": {"__min__": None},
         "max_key": {"__max__": None},
+        "int32_val": {"__int__": 42},
     }
 
 

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

@@ -51,7 +51,12 @@
 from google.cloud import firestore_v1 as firestore
 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 BSONMaxKey, BSONMinKey, BSONObjectId
+from google.cloud.firestore_v1.bson import (
+    BSONInt32,
+    BSONMaxKey,
+    BSONMinKey,
+    BSONObjectId,
+)
 from google.cloud.firestore_v1.query_profile import (
     ExecutionStats,
     ExplainMetrics,
@@ -1259,6 +1264,7 @@ async def test_async_bson_document_writes(client, cleanup, database):
         "user_id": BSONObjectId("507f191e810c19729de860ea"),
         "min_key": BSONMinKey(),
         "max_key": BSONMaxKey(),
+        "int32_val": BSONInt32(42),
     }
 
     await doc_ref.set(bson_payload)
@@ -1269,6 +1275,7 @@ async def test_async_bson_document_writes(client, cleanup, database):
         "user_id": {"__oid__": "507f191e810c19729de860ea"},
         "min_key": {"__min__": None},
         "max_key": {"__max__": None},
+        "int32_val": {"__int__": 42},
     }
 
 

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

@@ -21,6 +21,7 @@
 import pytest
 
 from google.cloud.firestore_v1.bson import (
+    BSONInt32,
     BSONMaxKey,
     BSONMinKey,
     BSONObjectId,
@@ -195,3 +196,74 @@ def test_bson_maxkey_copy():
 def test_bson_maxkey_pickle():
     key = BSONMaxKey()
     assert pickle.loads(pickle.dumps(key)) == key
+
+
+def test_bson_int32_valid():
+    val = BSONInt32(42)
+    assert val.value == 42
+    assert int(val) == 42
+    assert str(val) == "42"
+    assert repr(val) == "BSONInt32(42)"
+    assert val._to_map_value() == {"__int__": 42}
+
+
+def test_bson_int32_boundaries():
+    min_val = BSONInt32(-2147483648)
+    max_val = BSONInt32(2147483647)
+    assert min_val.value == -2147483648
+    assert max_val.value == 2147483647
+
+
+@pytest.mark.parametrize(
+    "invalid_input, exc_type, match_msg",
+    [
+        (2147483648, ValueError, "between -2147483648 and 2147483647"),
+        (-2147483649, ValueError, "between -2147483648 and 2147483647"),
+        ("42", TypeError, "requires an int"),
+        (42.0, TypeError, "requires an int"),
+        (True, TypeError, "requires an int"),
+        (False, TypeError, "requires an int"),
+        (None, TypeError, "requires an int"),
+    ],
+)
+def test_bson_int32_invalid(invalid_input, exc_type, match_msg):
+    with pytest.raises(exc_type, match=match_msg):
+        BSONInt32(invalid_input)
+
+
+def test_bson_int32_equality():
+    val1 = BSONInt32(42)
+    val2 = BSONInt32(42)
+    val3 = BSONInt32(100)
+
+    assert val1 == val2
+    assert val1 != val3
+    assert val1 != 42  # BSONInt32 is not equal to plain int
+
+    class CooperativeOther:
+        def __eq__(self, other):
+            return True
+
+    assert val1 == CooperativeOther()
+
+
+def test_bson_int32_hash_and_dict_key():
+    val1 = BSONInt32(42)
+    val2 = BSONInt32(42)
+
+    assert hash(val1) == hash(val2)
+    assert hash(val1) != hash(42)
+    lookup = {val1: "success"}
+    assert lookup[val2] == "success"
+    assert len({val1, val2}) == 1
+
+
+def test_bson_int32_copy():
+    val = BSONInt32(42)
+    assert copy.copy(val) == val
+    assert copy.deepcopy(val) == val
+
+
+def test_bson_int32_pickle():
+    val = BSONInt32(42)
+    assert pickle.loads(pickle.dumps(val)) == val