refactor(firestore): restore precise return types and docstrings on decode_value

- Restore full Union return type with _BSONType on decode_value.
- Restore Returns and Raises docstring sections in decode_value matching base branch.
- Remove unused _BSON_DECODERS import from _helpers.py.
- Revert extraneous changes to pipeline_result.py.

Towards #18402

Author: ohmayr

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

@@ -44,7 +44,7 @@
 import google
 from google.cloud import exceptions  # type: ignore
 from google.cloud.firestore_v1 import transforms, types
-from google.cloud.firestore_v1.bson import _BSON_DECODERS, _BSONType
+from google.cloud.firestore_v1.bson import _BSONType
 from google.cloud.firestore_v1.field_path import FieldPath, parse_field_path
 from google.cloud.firestore_v1.types import common, document, write
 from google.cloud.firestore_v1.types.write import DocumentTransform
@@ -347,7 +347,22 @@ def reference_value_to_document(reference_value, client) -> Any:
     return document
 
 
-def decode_value(value, client=None) -> Any:
+def decode_value(
+    value, client=None
+) -> Union[
+    None,
+    bool,
+    int,
+    float,
+    list,
+    datetime.datetime,
+    str,
+    bytes,
+    dict,
+    GeoPoint,
+    Vector,
+    _BSONType,
+]:
     """Converts a Firestore protobuf ``Value`` to a native Python value.
 
     Args:
@@ -357,10 +372,15 @@ def decode_value(value, client=None) -> Any:
             A client that has a document factory.
 
     Returns:
-        Any: A native Python value converted from the ``value``.
+        Union[NoneType, bool, int, float, datetime.datetime, \
+            str, bytes, dict, ~google.cloud.Firestore.GeoPoint, \
+            ~google.cloud.firestore_v1.vector.Vector, \
+            ~google.cloud.firestore_v1.bson._BSONType]: A native \
+        Python value converted from the ``value``.
 
     Raises:
-        ValueError: If ``value_type`` is unknown or unsupported.
+        NotImplementedError: If the ``value_type`` is ``reference_value``.
+        ValueError: If the ``value_type`` is unknown.
     """
     value_pb = getattr(value, "_pb", value)
     value_type = value_pb.WhichOneof("value_type")

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

@@ -44,7 +44,6 @@
     from google.cloud.firestore_v1.async_transaction import AsyncTransaction
     from google.cloud.firestore_v1.base_client import BaseClient
     from google.cloud.firestore_v1.base_document import BaseDocumentReference
-    from google.cloud.firestore_v1.bson import _BSONType
     from google.cloud.firestore_v1.client import Client
     from google.cloud.firestore_v1.pipeline import Pipeline
     from google.cloud.firestore_v1.pipeline_expressions import Constant
@@ -139,7 +138,7 @@ def __eq__(self, other: object) -> bool:
             return NotImplemented
         return (self._ref == other._ref) and (self._fields_pb == other._fields_pb)
 
-    def data(self) -> dict | "Vector" | "_BSONType" | None:
+    def data(self) -> dict | "Vector" | None:
         """
         Retrieves all fields in the result.