feat(firestore): add PyMongo duck-typing serialization support

[ohmayr]

Adds duck-typing detection in encode_value() for native PyMongo / third-party BSON objects (bson.ObjectId, bson.Decimal128, bson.Regex, bson.Timestamp, bson.MinKey, bson.MaxKey).

Allows applications migrating from MongoDB that use native PyMongo BSON objects to write directly to Firestore without triggering TypeError serialization failures or requiring manual type conversions.

Note that this is optional work and can be skipped. We can discuss this offline.

Fixes b/562164315 🦕

[gemini-code-assist]

Code Review

This pull request adds duck-typing support for native PyMongo and third-party BSON objects (such as ObjectId, Decimal128, Regex, Timestamp, MinKey, and MaxKey) within the encode_value helper function, along with corresponding unit tests. The review feedback suggests optimizing this performance-critical code path by using an O(1) set lookup for class names to avoid unnecessary attribute checks and recommends running benchmarks to verify that these changes do not introduce performance regressions.

[gemini-code-assist]

The encode_value function is a critical hot path called recursively for every field of every document during serialization. While the proposed change aims to optimize standard types using an O(1) set lookup, any changes to this performance-critical code path must be validated and benchmarked to ensure they do not degrade performance or eliminate fast-path optimizations (such as the overhead of double getattr calls). Please run benchmarks to verify the performance impact of this change.

    cls_name = getattr(getattr(value, "__class__", None), "__name__", None)
    if cls_name in {"ObjectId", "Decimal128", "Regex", "Timestamp", "MinKey", "MaxKey"}:
        if cls_name == "ObjectId" and hasattr(value, "binary"):
            return encode_value({"__oid__": str(value).lower()})
        elif cls_name == "Decimal128" and hasattr(value, "to_decimal"):
            return encode_value({"__decimal128__": str(value)})
        elif cls_name == "Regex" and hasattr(value, "pattern"):
            opts = getattr(value, "flags", "") or getattr(value, "options", "")
            return encode_value(
                {"__regex__": {"pattern": value.pattern, "options": str(opts)}}
            )
        elif cls_name == "Timestamp" and hasattr(value, "time") and hasattr(value, "inc"):
            return encode_value(
                {
                    "__request_timestamp__": {
                        "seconds": value.time,
                        "increment": value.inc,
                    }
                }
            )
        elif cls_name == "MinKey":
            return encode_value({"__min__": None})
        elif cls_name == "MaxKey":
            return encode_value({"__max__": None})

References

1. For performance-critical code paths executed on every request, validate and benchmark any proposed readability simplifications to ensure they do not degrade performance or eliminate fast-path optimizations.

[ohmayr]

Addressed: Moved the duck-typing inspection entirely out of the standard serialization hot path down to the fallback position right before TypeError is raised. Standard native Python types (int, float, str, dict, list, etc.) and native Firestore types bypass this check completely with zero overhead.

[daniel-sanche]

it looks like we should add to this type here

[ohmayr]

Done! Updated the encode_value docstring Args to include ~google.cloud.firestore_v1.bson._BSONType as well as supported BSON / PyMongo-compatible types.

[daniel-sanche]

Can opts here be non-string? Gemini flagged this as a potential issue

(I know I started a thread suggesting to not support int, but I don't feel too strongly one way or the other if it would make things easier here. We just need to make sure we're communicating what flags we accept and what we reject clearly)

[daniel-sanche]

I think some of the BSON constructors raise ValueError or others. We should probably either update this docstring to be exhaustive, or catch and wrap the errors raised in _try_duck_type_bson

[daniel-sanche]

It looks like PyMongo Binary types would be caught here before reaching _try_duck_type_bson. This means we would lose the subtype field