chore(firestore): prep for firestore pipelines GA (#16549)

Misc changes in prep for GA release of pipelines:

- re-enable releases for firestore
- remove notes about pipelines being in preview
    - added individual beta labels for search/dml classes and methods
- expose options in raw_stage
- renamed Type to PipelineDataType
- moved helper classes (options, enums) into pipeline_types
- expose pipeline classes in top-level \_\_init__.py

Author: daniel-sanche

.librarian/config.yaml

@@ -14,8 +14,6 @@ libraries:
   - id: bigframes
     release_blocked: true
   - generate_blocked: true
-    id: google-cloud-firestore
-    release_blocked: true
   - generate_blocked: true
     id: google-cloud-dialogflow
   - id: google-crc32c

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

@@ -30,6 +30,8 @@
     AsyncClient,
     AsyncCollectionReference,
     AsyncDocumentReference,
+    AsyncPipeline,
+    AsyncPipelineStream,
     AsyncQuery,
     AsyncTransaction,
     AsyncWriteBatch,
@@ -43,15 +45,31 @@
     ExistsOption,
     ExplainOptions,
     FieldFilter,
+    FindNearestOptions,
     GeoPoint,
     Increment,
     LastUpdateOption,
     Maximum,
     Minimum,
     Or,
+    Ordering,
+    Pipeline,
+    PipelineDataType,
+    PipelineExplainOptions,
+    PipelineResult,
+    PipelineSnapshot,
+    PipelineSource,
+    PipelineStream,
     Query,
     ReadAfterWriteError,
+    SampleOptions,
+    SearchOptions,
+    SubPipeline,
+    TimeGranularity,
+    TimePart,
+    TimeUnit,
     Transaction,
+    UnnestOptions,
     Watch,
     WriteBatch,
     WriteOption,
@@ -68,6 +86,8 @@
     "AsyncClient",
     "AsyncCollectionReference",
     "AsyncDocumentReference",
+    "AsyncPipeline",
+    "AsyncPipelineStream",
     "AsyncQuery",
     "async_transactional",
     "AsyncTransaction",
@@ -83,18 +103,34 @@
     "ExistsOption",
     "ExplainOptions",
     "FieldFilter",
+    "FindNearestOptions",
     "GeoPoint",
     "Increment",
     "LastUpdateOption",
     "Maximum",
     "Minimum",
     "Or",
+    "Ordering",
+    "Pipeline",
+    "PipelineDataType",
+    "PipelineExplainOptions",
+    "PipelineResult",
+    "PipelineSnapshot",
+    "PipelineSource",
+    "PipelineStream",
     "Query",
     "ReadAfterWriteError",
     "SERVER_TIMESTAMP",
+    "SampleOptions",
+    "SearchOptions",
+    "SubPipeline",
+    "TimeGranularity",
+    "TimePart",
+    "TimeUnit",
     "Transaction",
     "transactional",
     "types",
+    "UnnestOptions",
     "Watch",
     "WriteBatch",
     "WriteOption",

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

@@ -33,20 +33,44 @@
 from google.cloud.firestore_v1.async_client import AsyncClient
 from google.cloud.firestore_v1.async_collection import AsyncCollectionReference
 from google.cloud.firestore_v1.async_document import AsyncDocumentReference
+from google.cloud.firestore_v1.async_pipeline import AsyncPipeline
 from google.cloud.firestore_v1.async_query import AsyncQuery
 from google.cloud.firestore_v1.async_transaction import (
     AsyncTransaction,
     async_transactional,
 )
 from google.cloud.firestore_v1.base_aggregation import CountAggregation
 from google.cloud.firestore_v1.base_document import DocumentSnapshot
+from google.cloud.firestore_v1.base_pipeline import SubPipeline
 from google.cloud.firestore_v1.base_query import And, FieldFilter, Or
 from google.cloud.firestore_v1.batch import WriteBatch
 from google.cloud.firestore_v1.client import Client
 from google.cloud.firestore_v1.collection import CollectionReference
 from google.cloud.firestore_v1.document import DocumentReference
+from google.cloud.firestore_v1.pipeline import Pipeline
+from google.cloud.firestore_v1.pipeline_result import (
+    AsyncPipelineStream,
+    PipelineResult,
+    PipelineSnapshot,
+    PipelineStream,
+)
+from google.cloud.firestore_v1.pipeline_source import PipelineSource
+from google.cloud.firestore_v1.pipeline_types import (
+    FindNearestOptions,
+    Ordering,
+    PipelineDataType,
+    SampleOptions,
+    SearchOptions,
+    TimeGranularity,
+    TimePart,
+    TimeUnit,
+    UnnestOptions,
+)
 from google.cloud.firestore_v1.query import CollectionGroup, Query
-from google.cloud.firestore_v1.query_profile import ExplainOptions
+from google.cloud.firestore_v1.query_profile import (
+    ExplainOptions,
+    PipelineExplainOptions,
+)
 from google.cloud.firestore_v1.transaction import Transaction, transactional
 from google.cloud.firestore_v1.transforms import (
     DELETE_FIELD,
@@ -115,6 +139,8 @@
     "AsyncClient",
     "AsyncCollectionReference",
     "AsyncDocumentReference",
+    "AsyncPipeline",
+    "AsyncPipelineStream",
     "AsyncQuery",
     "async_transactional",
     "AsyncTransaction",
@@ -130,18 +156,34 @@
     "ExistsOption",
     "ExplainOptions",
     "FieldFilter",
+    "FindNearestOptions",
     "GeoPoint",
     "Increment",
     "LastUpdateOption",
     "Maximum",
     "Minimum",
     "Or",
+    "Ordering",
+    "Pipeline",
+    "PipelineDataType",
+    "PipelineExplainOptions",
+    "PipelineResult",
+    "PipelineSnapshot",
+    "PipelineSource",
+    "PipelineStream",
     "Query",
     "ReadAfterWriteError",
     "SERVER_TIMESTAMP",
+    "SampleOptions",
+    "SearchOptions",
+    "SubPipeline",
+    "TimeGranularity",
+    "TimePart",
+    "TimeUnit",
     "Transaction",
     "transactional",
     "types",
+    "UnnestOptions",
     "Watch",
     "WriteBatch",
     "WriteOption",

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

@@ -11,11 +11,6 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-"""
-.. warning::
-    **Preview API**: Firestore Pipelines is currently in preview and is
-    subject to potential breaking changes in future releases
-"""
 
 from __future__ import annotations
 
@@ -61,9 +56,7 @@ class AsyncPipeline(_BasePipeline):
 
     Use `client.pipeline()` to create instances of this class.
 
-    .. warning::
-        **Preview API**: Firestore Pipelines is currently in preview and is
-        subject to potential breaking changes in future releases
+
     """
 
     _client: AsyncClient

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

@@ -18,6 +18,7 @@
 
 
 from google.cloud.firestore_v1 import pipeline_stages as stages
+from google.cloud.firestore_v1 import pipeline_types as types
 from google.cloud.firestore_v1.base_vector_query import DistanceMeasure
 from google.cloud.firestore_v1.pipeline_expressions import (
     AggregateFunction,
@@ -37,6 +38,7 @@
 if TYPE_CHECKING:  # pragma: NO COVER
     from google.cloud.firestore_v1.async_client import AsyncClient
     from google.cloud.firestore_v1.client import Client
+    from google.cloud.firestore_v1.types.document import Value
 
 _T = TypeVar("_T", bound="_BasePipeline")
 
@@ -274,7 +276,7 @@ def find_nearest(
         field: str | Expression,
         vector: Sequence[float] | "Vector",
         distance_measure: "DistanceMeasure",
-        options: stages.FindNearestOptions | None = None,
+        options: types.FindNearestOptions | None = None,
     ) -> "_BasePipeline":
         """
         Performs vector distance (similarity) search with given parameters on the
@@ -395,11 +397,14 @@ def sort(self, *orders: stages.Ordering) -> "_BasePipeline":
         return self._append(stages.Sort(*orders))
 
     def search(
-        self, query_or_options: str | BooleanExpression | stages.SearchOptions
+        self, query_or_options: str | BooleanExpression | types.SearchOptions
     ) -> "_BasePipeline":
         """
         Adds a search stage to the pipeline.
 
+        .. note::
+            This feature is currently in beta and is subject to change.
+
         This stage filters documents based on the provided query expression.
 
         Example:
@@ -425,7 +430,7 @@ def search(
         """
         return self._append(stages.Search(query_or_options))
 
-    def sample(self, limit_or_options: int | stages.SampleOptions) -> "_BasePipeline":
+    def sample(self, limit_or_options: int | types.SampleOptions) -> "_BasePipeline":
         """
         Performs a pseudo-random sampling of the documents from the previous stage.
 
@@ -489,7 +494,7 @@ def unnest(
         self,
         field: str | Selectable,
         alias: str | Field | None = None,
-        options: stages.UnnestOptions | None = None,
+        options: types.UnnestOptions | None = None,
     ) -> "_BasePipeline":
         """
         Produces a document for each element in an array field from the previous stage document.
@@ -548,7 +553,12 @@ def unnest(
         """
         return self._append(stages.Unnest(field, alias, options))
 
-    def raw_stage(self, name: str, *params: Expression) -> "_BasePipeline":
+    def raw_stage(
+        self,
+        name: str,
+        *params: Expression,
+        options: dict[str, Expression | Value] | None = None,
+    ) -> "_BasePipeline":
         """
         Adds a stage to the pipeline by specifying the stage name as an argument. This does not offer any
         type safety on the stage params and requires the caller to know the order (and optionally names)
@@ -566,11 +576,12 @@ def raw_stage(self, name: str, *params: Expression) -> "_BasePipeline":
         Args:
             name: The name of the stage.
             *params: A sequence of `Expression` objects representing the parameters for the stage.
+            options: An optional dictionary of stage options.
 
         Returns:
             A new Pipeline object with this stage appended to the stage list
         """
-        return self._append(stages.RawStage(name, *params))
+        return self._append(stages.RawStage(name, *params, options=options or {}))
 
     def offset(self, offset: int) -> "_BasePipeline":
         """
@@ -704,6 +715,9 @@ def delete(self) -> "_BasePipeline":
         """
         Deletes the documents from the current pipeline stage.
 
+        .. note::
+            This feature is currently in beta and is subject to change.
+
         Example:
             >>> from google.cloud.firestore_v1.pipeline_expressions import Field
             >>> pipeline = client.pipeline().collection("logs")
@@ -720,6 +734,9 @@ def update(self, *transformed_fields: "Selectable") -> "_BasePipeline":
         """
         Performs an update operation using documents from previous stages.
 
+        .. note::
+            This feature is currently in beta and is subject to change.
+
         If called without `transformed_fields`, this method updates the documents in
         place based on the data flowing through the pipeline.
 

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

@@ -11,11 +11,6 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-"""
-.. warning::
-    **Preview API**: Firestore Pipelines is currently in preview and is
-    subject to potential breaking changes in future releases.
-"""
 
 from __future__ import annotations
 
@@ -58,9 +53,7 @@ class Pipeline(_BasePipeline):
 
     Use `client.pipeline()` to create instances of this class.
 
-    .. warning::
-        **Preview API**: Firestore Pipelines is currently in preview and is
-        subject to potential breaking changes in future releases.
+
     """
 
     _client: Client