feat: literals pipeline stage

Author: Linchin

google/cloud/firestore_v1/base_pipeline.py

@@ -273,6 +273,15 @@ def find_nearest(
             stages.FindNearest(field, vector, distance_measure, options)
         )
 
+    def literals(
+        self,
+        documents: Selectable,
+    ) -> "_BasePipeline":
+        """
+        TODO: add docstring.
+        """
+        return self._append(stages.Literals(documents))
+
     def replace_with(
         self,
         field: Selectable,

google/cloud/firestore_v1/pipeline_stages.py

@@ -342,6 +342,17 @@ def _pb_args(self):
         return [Value(integer_value=self.limit)]
 
 
+class Literals(Stage):
+    """TODO: add docstring."""
+
+    def __init__(self, documents: Selectable):
+        super().__init__("literals")
+        self.documents = Field(documents) if isinstance(documents, str) else documents
+
+    def _pb_args(self):
+        return [self.documents._to_pb()]
+
+
 class Offset(Stage):
     """Skips a specified number of documents."""
 

tests/system/pipeline_e2e/general.yaml

@@ -684,4 +684,27 @@ tests:
         - args:
           - fieldReferenceValue: awards
           - stringValue: full_replace
-          name: replace_with
+          name: replace_with
+  - description: literals
+    pipeline:
+      - Literals:
+        - Constant:
+            - title: "The Hitchhiker's Guide to the Galaxy"
+              author: "Douglas Adams"
+    assert_results:
+      - title: "The Hitchhiker's Guide to the Galaxy"
+        author: "Douglas Adams"
+    assert_proto:
+      pipeline:
+        stages:
+        - args:
+          - arrayValue:
+              values:
+              - mapValue:
+                  fields:
+                    author:
+                      stringValue: "Douglas Adams"
+                    title:
+                      stringValue: "The Hitchhiker's Guide to the Galaxy"
+          name: literals
+  

tests/unit/v1/test_pipeline.py

@@ -392,6 +392,7 @@ def test_pipeline_execute_stream_equivalence():
         ),
         ("replace_with", ("name",), stages.ReplaceWith),
         ("replace_with", (Field.of("n"),), stages.ReplaceWith),
+        ("literals", (Field.of("a"),), stages.Literals),
         ("sort", (Field.of("n").descending(),), stages.Sort),
         ("sort", (Field.of("n").descending(), Field.of("m").ascending()), stages.Sort),
         ("sample", (10,), stages.Sample),

tests/unit/v1/test_pipeline_stages.py

@@ -516,6 +516,32 @@ def test_to_pb(self):
         assert len(result.options) == 0
 
 
+class TestLiterals:
+    def _make_one(self, *args, **kwargs):
+        return stages.Literals(*args, **kwargs)
+
+    def test_ctor(self):
+        val = Constant.of({"a": 1})
+        instance = self._make_one(val)
+        assert instance.documents == val
+        assert instance.name == "literals"
+
+    def test_repr(self):
+        val = Constant.of({"a": 1})
+        instance = self._make_one(val)
+        repr_str = repr(instance)
+        assert repr_str == "Literals(documents=Constant.of({'a': 1}))"
+
+    def test_to_pb(self):
+        val = Constant.of({"a": 1})
+        instance = self._make_one(val)
+        result = instance._to_pb()
+        assert result.name == "literals"
+        assert len(result.args) == 1
+        assert result.args[0].map_value.fields["a"].integer_value == 1
+        assert len(result.options) == 0
+
+
 class TestOffset:
     def _make_one(self, *args, **kwargs):
         return stages.Offset(*args, **kwargs)