/
base_batch.py
148 lines (123 loc) · 5.63 KB
/
base_batch.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
# Copyright 2020 Google LLC All rights reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# 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.
"""Helpers for batch requests to the Google Cloud Firestore API."""
from google.cloud.firestore_v1 import _helpers
# Types needed only for Type Hints
from google.cloud.firestore_v1.document import DocumentReference
from typing import Union
class BaseWriteBatch(object):
"""Accumulate write operations to be sent in a batch.
This has the same set of methods for write operations that
:class:`~google.cloud.firestore_v1.document.DocumentReference` does,
e.g. :meth:`~google.cloud.firestore_v1.document.DocumentReference.create`.
Args:
client (:class:`~google.cloud.firestore_v1.client.Client`):
The client that created this batch.
"""
def __init__(self, client) -> None:
self._client = client
self._write_pbs = []
self.write_results = None
self.commit_time = None
def _add_write_pbs(self, write_pbs: list) -> None:
"""Add `Write`` protobufs to this transaction.
This method intended to be over-ridden by subclasses.
Args:
write_pbs (List[google.cloud.proto.firestore.v1.\
write_pb2.Write]): A list of write protobufs to be added.
"""
self._write_pbs.extend(write_pbs)
def create(self, reference: DocumentReference, document_data: dict) -> None:
"""Add a "change" to this batch to create a document.
If the document given by ``reference`` already exists, then this
batch will fail when :meth:`commit`-ed.
Args:
reference (:class:`~google.cloud.firestore_v1.document.DocumentReference`):
A document reference to be created in this batch.
document_data (dict): Property names and values to use for
creating a document.
"""
write_pbs = _helpers.pbs_for_create(reference._document_path, document_data)
self._add_write_pbs(write_pbs)
def set(
self,
reference: DocumentReference,
document_data: dict,
merge: Union[bool, list] = False,
) -> None:
"""Add a "change" to replace a document.
See
:meth:`google.cloud.firestore_v1.document.DocumentReference.set` for
more information on how ``option`` determines how the change is
applied.
Args:
reference (:class:`~google.cloud.firestore_v1.document.DocumentReference`):
A document reference that will have values set in this batch.
document_data (dict):
Property names and values to use for replacing a document.
merge (Optional[bool] or Optional[List<apispec>]):
If True, apply merging instead of overwriting the state
of the document.
"""
if merge is not False:
write_pbs = _helpers.pbs_for_set_with_merge(
reference._document_path, document_data, merge
)
else:
write_pbs = _helpers.pbs_for_set_no_merge(
reference._document_path, document_data
)
self._add_write_pbs(write_pbs)
def update(
self,
reference: DocumentReference,
field_updates: dict,
option: _helpers.WriteOption = None,
) -> None:
"""Add a "change" to update a document.
See
:meth:`google.cloud.firestore_v1.document.DocumentReference.update`
for more information on ``field_updates`` and ``option``.
Args:
reference (:class:`~google.cloud.firestore_v1.document.DocumentReference`):
A document reference that will be updated in this batch.
field_updates (dict):
Field names or paths to update and values to update with.
option (Optional[:class:`~google.cloud.firestore_v1.client.WriteOption`]):
A write option to make assertions / preconditions on the server
state of the document before applying changes.
"""
if option.__class__.__name__ == "ExistsOption":
raise ValueError("you must not pass an explicit write option to " "update.")
write_pbs = _helpers.pbs_for_update(
reference._document_path, field_updates, option
)
self._add_write_pbs(write_pbs)
def delete(
self, reference: DocumentReference, option: _helpers.WriteOption = None
) -> None:
"""Add a "change" to delete a document.
See
:meth:`google.cloud.firestore_v1.document.DocumentReference.delete`
for more information on how ``option`` determines how the change is
applied.
Args:
reference (:class:`~google.cloud.firestore_v1.document.DocumentReference`):
A document reference that will be deleted in this batch.
option (Optional[:class:`~google.cloud.firestore_v1.client.WriteOption`]):
A write option to make assertions / preconditions on the server
state of the document before applying changes.
"""
write_pb = _helpers.pb_for_delete(reference._document_path, option)
self._add_write_pbs([write_pb])