feat: new transaction options for datastoreV1

google/cloud/datastore_v1/types/datastore.py

@@ -107,6 +107,12 @@ class LookupResponse(proto.Message):
             resource constraints. The order of results in
             this field is undefined and has no relation to
             the order of the keys in the input.
+        transaction (bytes):
+            The identifier of the transaction that was started as part
+            of this Lookup request.
+
+            Set only when [ReadOptions.begin_transaction][] was set in
+            [LookupRequest.read_options][google.datastore.v1.LookupRequest.read_options].
         read_time (google.protobuf.timestamp_pb2.Timestamp):
             The time at which these entities were read or
             found missing.
@@ -127,6 +133,10 @@ class LookupResponse(proto.Message):
         number=3,
         message=entity.Key,
     )
+    transaction: bytes = proto.Field(
+        proto.BYTES,
+        number=5,
+    )
     read_time: timestamp_pb2.Timestamp = proto.Field(
         proto.MESSAGE,
         number=7,
@@ -215,6 +225,12 @@ class RunQueryResponse(proto.Message):
         query (google.cloud.datastore_v1.types.Query):
             The parsed form of the ``GqlQuery`` from the request, if it
             was set.
+        transaction (bytes):
+            The identifier of the transaction that was started as part
+            of this RunQuery request.
+
+            Set only when [ReadOptions.begin_transaction][] was set in
+            [RunQueryRequest.read_options][google.datastore.v1.RunQueryRequest.read_options].
     """
 
     batch: gd_query.QueryResultBatch = proto.Field(
@@ -227,6 +243,10 @@ class RunQueryResponse(proto.Message):
         number=2,
         message=gd_query.Query,
     )
+    transaction: bytes = proto.Field(
+        proto.BYTES,
+        number=5,
+    )
 
 
 class RunAggregationQueryRequest(proto.Message):
@@ -311,6 +331,12 @@ class RunAggregationQueryResponse(proto.Message):
         query (google.cloud.datastore_v1.types.AggregationQuery):
             The parsed form of the ``GqlQuery`` from the request, if it
             was set.
+        transaction (bytes):
+            The identifier of the transaction that was started as part
+            of this RunAggregationQuery request.
+
+            Set only when [ReadOptions.begin_transaction][] was set in
+            [RunAggregationQueryRequest.read_options][google.datastore.v1.RunAggregationQueryRequest.read_options].
     """
 
     batch: aggregation_result.AggregationResultBatch = proto.Field(
@@ -323,6 +349,10 @@ class RunAggregationQueryResponse(proto.Message):
         number=2,
         message=gd_query.AggregationQuery,
     )
+    transaction: bytes = proto.Field(
+        proto.BYTES,
+        number=5,
+    )
 
 
 class BeginTransactionRequest(proto.Message):
@@ -416,6 +446,10 @@ class CommitRequest(proto.Message):
     r"""The request for
     [Datastore.Commit][google.datastore.v1.Datastore.Commit].
 
+    This message has `oneof`_ fields (mutually exclusive fields).
+    For each oneof, at most one member field can be set at the same time.
+    Setting any member of the oneof automatically clears all other
+    members.
 
     .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
 
@@ -436,6 +470,15 @@ class CommitRequest(proto.Message):
             commit. A transaction identifier is returned by a call to
             [Datastore.BeginTransaction][google.datastore.v1.Datastore.BeginTransaction].
 
+            This field is a member of `oneof`_ ``transaction_selector``.
+        single_use_transaction (google.cloud.datastore_v1.types.TransactionOptions):
+            Options for beginning a new transaction for this request.
+            The transaction is committed when the request completes. If
+            specified,
+            [TransactionOptions.mode][google.datastore.v1.TransactionOptions.mode]
+            must be
+            [TransactionOptions.ReadWrite][google.datastore.v1.TransactionOptions.ReadWrite].
+
             This field is a member of `oneof`_ ``transaction_selector``.
         mutations (MutableSequence[google.cloud.datastore_v1.types.Mutation]):
             The mutations to perform.
@@ -478,6 +521,12 @@ class Mode(proto.Enum):
         number=1,
         oneof="transaction_selector",
     )
+    single_use_transaction: "TransactionOptions" = proto.Field(
+        proto.MESSAGE,
+        number=10,
+        oneof="transaction_selector",
+        message="TransactionOptions",
+    )
     mutations: MutableSequence["Mutation"] = proto.RepeatedField(
         proto.MESSAGE,
         number=6,
@@ -769,6 +818,16 @@ class ReadOptions(proto.Message):
             transaction identifier is returned by a call to
             [Datastore.BeginTransaction][google.datastore.v1.Datastore.BeginTransaction].
 
+            This field is a member of `oneof`_ ``consistency_type``.
+        new_transaction (google.cloud.datastore_v1.types.TransactionOptions):
+            Options for beginning a new transaction for this request.
+
+            The new transaction identifier will be returned in the
+            corresponding response as either
+            [LookupResponse.transaction][google.datastore.v1.LookupResponse.transaction]
+            or
+            [RunQueryResponse.transaction][google.datastore.v1.RunQueryResponse.transaction].
+
             This field is a member of `oneof`_ ``consistency_type``.
         read_time (google.protobuf.timestamp_pb2.Timestamp):
             Reads entities as they were at the given
@@ -796,6 +855,12 @@ class ReadConsistency(proto.Enum):
         number=2,
         oneof="consistency_type",
     )
+    new_transaction: "TransactionOptions" = proto.Field(
+        proto.MESSAGE,
+        number=3,
+        oneof="consistency_type",
+        message="TransactionOptions",
+    )
     read_time: timestamp_pb2.Timestamp = proto.Field(
         proto.MESSAGE,
         number=4,

scripts/fixup_datastore_v1_keywords.py

@@ -41,7 +41,7 @@ class datastoreCallTransformer(cst.CSTTransformer):
     METHOD_TO_PARAMS: Dict[str, Tuple[str]] = {
         'allocate_ids': ('project_id', 'keys', 'database_id', ),
         'begin_transaction': ('project_id', 'database_id', 'transaction_options', ),
-        'commit': ('project_id', 'database_id', 'mode', 'transaction', 'mutations', ),
+        'commit': ('project_id', 'database_id', 'mode', 'transaction', 'single_use_transaction', 'mutations', ),
         'lookup': ('project_id', 'keys', 'database_id', 'read_options', ),
         'reserve_ids': ('project_id', 'keys', 'database_id', ),
         'rollback': ('project_id', 'transaction', 'database_id', ),

tests/unit/gapic/datastore_v1/test_datastore.py

@@ -683,7 +683,9 @@ def test_lookup(request_type, transport: str = "grpc"):
     # Mock the actual call within the gRPC stub, and fake the request.
     with mock.patch.object(type(client.transport.lookup), "__call__") as call:
         # Designate an appropriate return value for the call.
-        call.return_value = datastore.LookupResponse()
+        call.return_value = datastore.LookupResponse(
+            transaction=b"transaction_blob",
+        )
         response = client.lookup(request)
 
         # Establish that the underlying gRPC stub method was called.
@@ -693,6 +695,7 @@ def test_lookup(request_type, transport: str = "grpc"):
 
     # Establish that the response is the type that we expect.
     assert isinstance(response, datastore.LookupResponse)
+    assert response.transaction == b"transaction_blob"
 
 
 def test_lookup_empty_call():
@@ -728,7 +731,9 @@ async def test_lookup_async(
     with mock.patch.object(type(client.transport.lookup), "__call__") as call:
         # Designate an appropriate return value for the call.
         call.return_value = grpc_helpers_async.FakeUnaryUnaryCall(
-            datastore.LookupResponse()
+            datastore.LookupResponse(
+                transaction=b"transaction_blob",
+            )
         )
         response = await client.lookup(request)
 
@@ -739,6 +744,7 @@ async def test_lookup_async(
 
     # Establish that the response is the type that we expect.
     assert isinstance(response, datastore.LookupResponse)
+    assert response.transaction == b"transaction_blob"
 
 
 @pytest.mark.asyncio
@@ -941,7 +947,9 @@ def test_run_query(request_type, transport: str = "grpc"):
     # Mock the actual call within the gRPC stub, and fake the request.
     with mock.patch.object(type(client.transport.run_query), "__call__") as call:
         # Designate an appropriate return value for the call.
-        call.return_value = datastore.RunQueryResponse()
+        call.return_value = datastore.RunQueryResponse(
+            transaction=b"transaction_blob",
+        )
         response = client.run_query(request)
 
         # Establish that the underlying gRPC stub method was called.
@@ -951,6 +959,7 @@ def test_run_query(request_type, transport: str = "grpc"):
 
     # Establish that the response is the type that we expect.
     assert isinstance(response, datastore.RunQueryResponse)
+    assert response.transaction == b"transaction_blob"
 
 
 def test_run_query_empty_call():
@@ -986,7 +995,9 @@ async def test_run_query_async(
     with mock.patch.object(type(client.transport.run_query), "__call__") as call:
         # Designate an appropriate return value for the call.
         call.return_value = grpc_helpers_async.FakeUnaryUnaryCall(
-            datastore.RunQueryResponse()
+            datastore.RunQueryResponse(
+                transaction=b"transaction_blob",
+            )
         )
         response = await client.run_query(request)
 
@@ -997,6 +1008,7 @@ async def test_run_query_async(
 
     # Establish that the response is the type that we expect.
     assert isinstance(response, datastore.RunQueryResponse)
+    assert response.transaction == b"transaction_blob"
 
 
 @pytest.mark.asyncio
@@ -1067,7 +1079,9 @@ def test_run_aggregation_query(request_type, transport: str = "grpc"):
         type(client.transport.run_aggregation_query), "__call__"
     ) as call:
         # Designate an appropriate return value for the call.
-        call.return_value = datastore.RunAggregationQueryResponse()
+        call.return_value = datastore.RunAggregationQueryResponse(
+            transaction=b"transaction_blob",
+        )
         response = client.run_aggregation_query(request)
 
         # Establish that the underlying gRPC stub method was called.
@@ -1077,6 +1091,7 @@ def test_run_aggregation_query(request_type, transport: str = "grpc"):
 
     # Establish that the response is the type that we expect.
     assert isinstance(response, datastore.RunAggregationQueryResponse)
+    assert response.transaction == b"transaction_blob"
 
 
 def test_run_aggregation_query_empty_call():
@@ -1116,7 +1131,9 @@ async def test_run_aggregation_query_async(
     ) as call:
         # Designate an appropriate return value for the call.
         call.return_value = grpc_helpers_async.FakeUnaryUnaryCall(
-            datastore.RunAggregationQueryResponse()
+            datastore.RunAggregationQueryResponse(
+                transaction=b"transaction_blob",
+            )
         )
         response = await client.run_aggregation_query(request)
 
@@ -1127,6 +1144,7 @@ async def test_run_aggregation_query_async(
 
     # Establish that the response is the type that we expect.
     assert isinstance(response, datastore.RunAggregationQueryResponse)
+    assert response.transaction == b"transaction_blob"
 
 
 @pytest.mark.asyncio