feat(firestore): add BSON read deserialization support

[ohmayr]

Adds opt-in BSON read deserialization support to the Google Cloud Firestore Python SDK.
When enabled via decode_bson=True, document fields containing BSON wire map structures returned by Firestore (such as {"__oid__": "507f191e810c19729de860ea"}) are automatically deserialized into their corresponding Python BSON container instances (BSONObjectId, BSONDecimal128, BSONTimestamp, BSONRegex, BSONBinary, BSONInt32, BSONMinKey, BSONMaxKey).

💻 Usage

Default Behavior (decode_bson=False)

Existing applications continue to receive raw map dictionaries by default to preserve 100% backward compatibility:

client = firestore.Client()
doc = client.collection("users").document("doc1").get()

Opt-in Behavior (decode_bson=True)

client = firestore.Client(decode_bson=True)
doc = client.collection("users").document("doc1").get()
# Returns deserialized BSON instance: {"user_id": BSONObjectId("507f191e810c19729de860ea")}
data = doc.to_dict()

🏛️ Design Decisions

1. Opt-In decode_bson=False Default (Enterprise Backward Safety): Defaulting to decode_bson=False ensures existing production code accessing raw dictionary keys (dict["user_id"]["oid"]) will not break upon upgrading the SDK.

2. Subtype 0 Binary Deserialization: Wire maps representing Subtype 0 BSON Binary (v[0] == 0) are deserialized into native Python bytes (b"..."), while non-zero subtypes ($1 \le v[0] \le 255$) deserialize into BSONBinary(data, subtype=v[0]) objects.

3. Explicit Non-None Fallback Control: Updated decode_dict() to explicitly check if decoded is not None: rather than relying on Python truthiness (or), preventing false fallback on empty byte payloads (b"") or falsy objects.

4. Recursive Nested Map & Array Support: Added _decode_bson_dict_recursive() to ensure BSON wire maps inside nested dictionaries and array elements are deserialized properly.

Fixes b/562164140 🦕

[gemini-code-assist]

Code Review

This pull request introduces several new BSON types (BSONInt32, BSONBinary, BSONTimestamp, BSONRegex, and BSONDecimal128) to the Firestore Python client, along with their respective decoders, integration tests, and unit tests. Feedback on these changes highlights a violation of Python's hash contract in BSONDecimal128 due to mixed-type equality with decimal.Decimal without matching hashes. Additionally, the reviewer recommended replacing the boolean or fallback logic in decode_dict with an explicit None check to prevent potential bugs with falsy decoded BSON objects.

[daniel-sanche]

Can we do this without changing this to Any? Can't we just add BSONType to the output list?

This would remove a lot of the value of the type annotations

[daniel-sanche]

Why did you drop the Raises section?

[daniel-sanche]

Why does this need 3 states? Can't it just be a bool that defaults to False?

[daniel-sanche]

Can we have this opted in by default? It looks like other languages decode to BSON by default. And we do similar decoding to custom objects for GeoPoint, Vector, etc. Making this opt-in would really lower the value of for the feature

BSON is a new feature, so we wouldn't expect workarounds in existing code. But let me know if you have any specific breaking change concerns, and maybe we can find solutions

[daniel-sanche]

This seems like it should be implemented as a class method:

BSONType._from_dict(data)

or

BSONType._class_for_key(key)(value)