feat(firestore): add BSONTimestamp support

Author: ohmayr

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

@@ -75,6 +75,7 @@ replacements:
           BSONMaxKey,
           BSONMinKey,
           BSONObjectId,
+          BSONTimestamp,
       )
       from google.cloud.firestore_v1.client import Client
       from google.cloud.firestore_v1.collection import CollectionReference
@@ -182,6 +183,7 @@ replacements:
           "BSONMaxKey",
           "BSONMinKey",
           "BSONObjectId",
+          "BSONTimestamp",
           "Client",
           "CountAggregation",
           "CollectionGroup",
@@ -259,6 +261,7 @@ replacements:
           BSONMaxKey,
           BSONMinKey,
           BSONObjectId,
+          BSONTimestamp,
           Client,
           CollectionGroup,
           CollectionReference,
@@ -321,6 +324,7 @@ replacements:
           "BSONMaxKey",
           "BSONMinKey",
           "BSONObjectId",
+          "BSONTimestamp",
           "Client",
           "CountAggregation",
           "CollectionGroup",

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

@@ -40,6 +40,7 @@
     BSONMaxKey,
     BSONMinKey,
     BSONObjectId,
+    BSONTimestamp,
     Client,
     CollectionGroup,
     CollectionReference,
@@ -102,6 +103,7 @@
     "BSONMaxKey",
     "BSONMinKey",
     "BSONObjectId",
+    "BSONTimestamp",
     "Client",
     "CountAggregation",
     "CollectionGroup",

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

@@ -52,6 +52,7 @@
     BSONMaxKey,
     BSONMinKey,
     BSONObjectId,
+    BSONTimestamp,
 )
 from google.cloud.firestore_v1.client import Client
 from google.cloud.firestore_v1.collection import CollectionReference
@@ -159,6 +160,7 @@
     "BSONMaxKey",
     "BSONMinKey",
     "BSONObjectId",
+    "BSONTimestamp",
     "Client",
     "CountAggregation",
     "CollectionGroup",

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

@@ -34,6 +34,7 @@
     "BSONMaxKey",
     "BSONInt32",
     "BSONBinary",
+    "BSONTimestamp",
 ]
 
 _OBJECT_ID_BYTES_LEN = 12
@@ -287,3 +288,85 @@ def __eq__(self, other: Any) -> bool:
 
     def __hash__(self) -> int:
         return hash((type(self), self._data, self._subtype))
+
+
+class BSONTimestamp(_BSONType):
+    """Represents a BSON Timestamp container for Firestore operation log entries.
+
+    Args:
+        seconds (int): Timestamp seconds as a signed int32 (-2^31 to 2^31-1) or unsigned long (0 to 2^32-1).
+        increment (int): Timestamp increment as a signed int32 (-2^31 to 2^31-1) or unsigned long (0 to 2^32-1).
+
+    Raises:
+        TypeError: If seconds or increment is not an integer or is a boolean.
+        ValueError: If seconds or increment is outside -2^31 to 2^32-1 range.
+
+    Example:
+        >>> ts = BSONTimestamp(1700000000, 1)
+        >>> ts.seconds
+        1700000000
+        >>> ts.increment
+        1
+        >>> ts_neg = BSONTimestamp(-1, -1)
+        >>> ts_neg.seconds
+        4294967295
+        >>> ts_neg.increment
+        4294967295
+    """
+
+    __slots__ = ("_seconds", "_increment")
+
+    _MIN_VALUE: int = 0
+    _MAX_VALUE: int = (1 << 32) - 1
+    _MIN_INT32: int = -(1 << 31)
+
+    def __init__(self, seconds: int, increment: int):
+        self._seconds: int = self._validate_and_convert_to_unsigned(seconds, "seconds")
+        self._increment: int = self._validate_and_convert_to_unsigned(
+            increment, "increment"
+        )
+
+    @classmethod
+    def _validate_and_convert_to_unsigned(cls, val: int, name: str) -> int:
+        """Validates integer input and converts signed int32 to unsigned long representation."""
+        if isinstance(val, bool) or not isinstance(val, int):
+            raise TypeError(f"BSONTimestamp {name} must be an int.")
+        if cls._MIN_INT32 <= val < 0:
+            val = val % (1 << 32)
+        if not (cls._MIN_VALUE <= val <= cls._MAX_VALUE):
+            raise ValueError(
+                f"BSONTimestamp {name} must be between {cls._MIN_VALUE} and {cls._MAX_VALUE}."
+            )
+        return val
+
+    @property
+    def seconds(self) -> int:
+        """int: The seconds value in unsigned long representation."""
+        return self._seconds
+
+    @property
+    def increment(self) -> int:
+        """int: The increment value in unsigned long representation."""
+        return self._increment
+
+    def _to_map_value(self) -> Dict[str, Dict[str, int]]:
+        """Returns map dictionary representation for wire serialization."""
+        return {
+            "__request_timestamp__": {
+                "seconds": self._seconds,
+                "increment": self._increment,
+            }
+        }
+
+    def __repr__(self) -> str:
+        return f"BSONTimestamp(seconds={self._seconds}, increment={self._increment})"
+
+    def __eq__(self, other: Any) -> bool:
+        if isinstance(other, BSONTimestamp):
+            return (
+                self._seconds == other._seconds and self._increment == other._increment
+            )
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash((type(self), self._seconds, self._increment))

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

@@ -64,6 +64,7 @@
     BSONMaxKey,
     BSONMinKey,
     BSONObjectId,
+    BSONTimestamp,
 )
 from google.cloud.firestore_v1.vector import Vector
 
@@ -1304,6 +1305,7 @@ def test_bson_document_writes(client, cleanup, database):
         "int32_val": BSONInt32(42),
         "binary_val_sub0": BSONBinary(b"hello", subtype=0),
         "binary_val_sub128": BSONBinary(b"world", subtype=128),
+        "timestamp_val": BSONTimestamp(1700000000, 1),
     }
 
     doc_ref.set(bson_payload)
@@ -1317,6 +1319,12 @@ def test_bson_document_writes(client, cleanup, database):
         "int32_val": {"__int__": 42},
         "binary_val_sub0": b"hello",
         "binary_val_sub128": {"__binary__": b"\x80world"},
+        "timestamp_val": {
+            "__request_timestamp__": {
+                "seconds": 1700000000,
+                "increment": 1,
+            }
+        },
     }
 
 

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

@@ -41,6 +41,7 @@
     BSONMaxKey,
     BSONMinKey,
     BSONObjectId,
+    BSONTimestamp,
 )
 from google.cloud.firestore_v1.query_profile import (
     ExecutionStats,
@@ -1267,6 +1268,7 @@ async def test_async_bson_document_writes(client, cleanup, database):
         "int32_val": BSONInt32(42),
         "binary_val_sub0": BSONBinary(b"hello", subtype=0),
         "binary_val_sub128": BSONBinary(b"world", subtype=128),
+        "timestamp_val": BSONTimestamp(1700000000, 1),
     }
 
     await doc_ref.set(bson_payload)
@@ -1280,6 +1282,12 @@ async def test_async_bson_document_writes(client, cleanup, database):
         "int32_val": {"__int__": 42},
         "binary_val_sub0": b"hello",
         "binary_val_sub128": {"__binary__": b"\x80world"},
+        "timestamp_val": {
+            "__request_timestamp__": {
+                "seconds": 1700000000,
+                "increment": 1,
+            }
+        },
     }
 
 

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

@@ -25,6 +25,7 @@
     BSONMaxKey,
     BSONMinKey,
     BSONObjectId,
+    BSONTimestamp,
     _BSONType,
 )
 
@@ -340,3 +341,83 @@ def test_bson_binary_copy():
 def test_bson_binary_pickle():
     val = BSONBinary(b"hello", subtype=5)
     assert pickle.loads(pickle.dumps(val)) == val
+
+
+def test_bson_timestamp_valid():
+    ts = BSONTimestamp(1700000000, 42)
+    assert ts.seconds == 1700000000
+    assert ts.increment == 42
+    assert ts._to_map_value() == {
+        "__request_timestamp__": {
+            "seconds": 1700000000,
+            "increment": 42,
+        }
+    }
+    assert repr(ts) == "BSONTimestamp(seconds=1700000000, increment=42)"
+
+
+def test_bson_timestamp_signed_int32_conversion():
+    # Negative signed 32-bit int inputs convert to unsigned uint32 per spec
+    ts1 = BSONTimestamp(-1, -1)
+    assert ts1.seconds == 4294967295
+    assert ts1.increment == 4294967295
+
+    ts2 = BSONTimestamp(-2147483648, -2147483648)
+    assert ts2.seconds == 2147483648
+    assert ts2.increment == 2147483648
+
+
+def test_bson_timestamp_boundaries():
+    ts_min = BSONTimestamp(0, 0)
+    ts_max = BSONTimestamp(4294967295, 4294967295)
+    assert ts_min.seconds == 0
+    assert ts_min.increment == 0
+    assert ts_max.seconds == 4294967295
+    assert ts_max.increment == 4294967295
+
+
+@pytest.mark.parametrize(
+    "sec_input, inc_input, exc_type, match_msg",
+    [
+        (-2147483649, 0, ValueError, "must be between"),
+        (0, -2147483649, ValueError, "must be between"),
+        (4294967296, 0, ValueError, "must be between"),
+        (0, 4294967296, ValueError, "must be between"),
+        (True, 0, TypeError, "seconds must be an int"),
+        (0, False, TypeError, "increment must be an int"),
+        ("1700000000", 0, TypeError, "seconds must be an int"),
+        (0, 1.5, TypeError, "increment must be an int"),
+    ],
+)
+def test_bson_timestamp_invalid_inputs(sec_input, inc_input, exc_type, match_msg):
+    with pytest.raises(exc_type, match=match_msg):
+        BSONTimestamp(sec_input, inc_input)
+
+
+def test_bson_timestamp_equality():
+    ts1 = BSONTimestamp(100, 1)
+    ts2 = BSONTimestamp(100, 1)
+    ts3 = BSONTimestamp(100, 2)
+    ts4 = BSONTimestamp(200, 1)
+    assert ts1 == ts2
+    assert ts1 != ts3
+    assert ts1 != ts4
+    assert ts1 != 100
+
+
+def test_bson_timestamp_hash_and_dict_key():
+    ts1 = BSONTimestamp(100, 1)
+    ts2 = BSONTimestamp(100, 1)
+    assert hash(ts1) == hash(ts2)
+    assert len({ts1, ts2}) == 1
+
+
+def test_bson_timestamp_copy():
+    ts = BSONTimestamp(100, 1)
+    assert copy.copy(ts) == ts
+    assert copy.deepcopy(ts) == ts
+
+
+def test_bson_timestamp_pickle():
+    ts = BSONTimestamp(100, 1)
+    assert pickle.loads(pickle.dumps(ts)) == ts