Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/google/cloud/firestore_v1/types/document.py: 100%

1# -*- coding: utf-8 -*- 

2# Copyright 2023 Google LLC 

3# 

4# Licensed under the Apache License, Version 2.0 (the "License"); 

5# you may not use this file except in compliance with the License. 

6# You may obtain a copy of the License at 

7# 

8# http://www.apache.org/licenses/LICENSE-2.0 

9# 

10# Unless required by applicable law or agreed to in writing, software 

11# distributed under the License is distributed on an "AS IS" BASIS, 

12# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 

13# See the License for the specific language governing permissions and 

14# limitations under the License. 

15# 

16from __future__ import annotations 

17 

18from typing import MutableMapping, MutableSequence 

19 

20import proto # type: ignore 

21 

22from google.protobuf import struct_pb2 # type: ignore 

23from google.protobuf import timestamp_pb2 # type: ignore 

24from google.type import latlng_pb2 # type: ignore 

25 

26 

27__protobuf__ = proto.module( 

28 package="google.firestore.v1", 

29 manifest={ 

30 "Document", 

31 "Value", 

32 "ArrayValue", 

33 "MapValue", 

34 }, 

35) 

36 

37 

38class Document(proto.Message): 

39 r"""A Firestore document. 

40 

41 Must not exceed 1 MiB - 4 bytes. 

42 

43 Attributes: 

44 name (str): 

45 The resource name of the document, for example 

46 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``. 

47 fields (MutableMapping[str, google.cloud.firestore_v1.types.Value]): 

48 The document's fields. 

49 

50 The map keys represent field names. 

51 

52 A simple field name contains only characters ``a`` to ``z``, 

53 ``A`` to ``Z``, ``0`` to ``9``, or ``_``, and must not start 

54 with ``0`` to ``9``. For example, ``foo_bar_17``. 

55 

56 Field names matching the regular expression ``__.*__`` are 

57 reserved. Reserved field names are forbidden except in 

58 certain documented contexts. The map keys, represented as 

59 UTF-8, must not exceed 1,500 bytes and cannot be empty. 

60 

61 Field paths may be used in other contexts to refer to 

62 structured fields defined here. For ``map_value``, the field 

63 path is represented by the simple or quoted field names of 

64 the containing fields, delimited by ``.``. For example, the 

65 structured field 

66 ``"foo" : { map_value: { "x&y" : { string_value: "hello" }}}`` 

67 would be represented by the field path ``foo.x&y``. 

68 

69 Within a field path, a quoted field name starts and ends 

70 with :literal:`\`` and may contain any character. Some 

71 characters, including :literal:`\``, must be escaped using a 

72 ``\``. For example, :literal:`\`x&y\`` represents ``x&y`` 

73 and :literal:`\`bak\`tik\`` represents :literal:`bak`tik`. 

74 create_time (google.protobuf.timestamp_pb2.Timestamp): 

75 Output only. The time at which the document was created. 

76 

77 This value increases monotonically when a document is 

78 deleted then recreated. It can also be compared to values 

79 from other documents and the ``read_time`` of a query. 

80 update_time (google.protobuf.timestamp_pb2.Timestamp): 

81 Output only. The time at which the document was last 

82 changed. 

83 

84 This value is initially set to the ``create_time`` then 

85 increases monotonically with each change to the document. It 

86 can also be compared to values from other documents and the 

87 ``read_time`` of a query. 

88 """ 

89 

90 name: str = proto.Field( 

91 proto.STRING, 

92 number=1, 

93 ) 

94 fields: MutableMapping[str, "Value"] = proto.MapField( 

95 proto.STRING, 

96 proto.MESSAGE, 

97 number=2, 

98 message="Value", 

99 ) 

100 create_time: timestamp_pb2.Timestamp = proto.Field( 

101 proto.MESSAGE, 

102 number=3, 

103 message=timestamp_pb2.Timestamp, 

104 ) 

105 update_time: timestamp_pb2.Timestamp = proto.Field( 

106 proto.MESSAGE, 

107 number=4, 

108 message=timestamp_pb2.Timestamp, 

109 ) 

110 

111 

112class Value(proto.Message): 

113 r"""A message that can hold any of the supported value types. 

114 

115 This message has `oneof`_ fields (mutually exclusive fields). 

116 For each oneof, at most one member field can be set at the same time. 

117 Setting any member of the oneof automatically clears all other 

118 members. 

119 

120 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields 

121 

122 Attributes: 

123 null_value (google.protobuf.struct_pb2.NullValue): 

124 A null value. 

125 

126 This field is a member of `oneof`_ ``value_type``. 

127 boolean_value (bool): 

128 A boolean value. 

129 

130 This field is a member of `oneof`_ ``value_type``. 

131 integer_value (int): 

132 An integer value. 

133 

134 This field is a member of `oneof`_ ``value_type``. 

135 double_value (float): 

136 A double value. 

137 

138 This field is a member of `oneof`_ ``value_type``. 

139 timestamp_value (google.protobuf.timestamp_pb2.Timestamp): 

140 A timestamp value. 

141 

142 Precise only to microseconds. When stored, any 

143 additional precision is rounded down. 

144 

145 This field is a member of `oneof`_ ``value_type``. 

146 string_value (str): 

147 A string value. 

148 

149 The string, represented as UTF-8, must not 

150 exceed 1 MiB - 89 bytes. Only the first 1,500 

151 bytes of the UTF-8 representation are considered 

152 by queries. 

153 

154 This field is a member of `oneof`_ ``value_type``. 

155 bytes_value (bytes): 

156 A bytes value. 

157 

158 Must not exceed 1 MiB - 89 bytes. 

159 Only the first 1,500 bytes are considered by 

160 queries. 

161 

162 This field is a member of `oneof`_ ``value_type``. 

163 reference_value (str): 

164 A reference to a document. For example: 

165 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``. 

166 

167 This field is a member of `oneof`_ ``value_type``. 

168 geo_point_value (google.type.latlng_pb2.LatLng): 

169 A geo point value representing a point on the 

170 surface of Earth. 

171 

172 This field is a member of `oneof`_ ``value_type``. 

173 array_value (google.cloud.firestore_v1.types.ArrayValue): 

174 An array value. 

175 

176 Cannot directly contain another array value, 

177 though can contain an map which contains another 

178 array. 

179 

180 This field is a member of `oneof`_ ``value_type``. 

181 map_value (google.cloud.firestore_v1.types.MapValue): 

182 A map value. 

183 

184 This field is a member of `oneof`_ ``value_type``. 

185 """ 

186 

187 null_value: struct_pb2.NullValue = proto.Field( 

188 proto.ENUM, 

189 number=11, 

190 oneof="value_type", 

191 enum=struct_pb2.NullValue, 

192 ) 

193 boolean_value: bool = proto.Field( 

194 proto.BOOL, 

195 number=1, 

196 oneof="value_type", 

197 ) 

198 integer_value: int = proto.Field( 

199 proto.INT64, 

200 number=2, 

201 oneof="value_type", 

202 ) 

203 double_value: float = proto.Field( 

204 proto.DOUBLE, 

205 number=3, 

206 oneof="value_type", 

207 ) 

208 timestamp_value: timestamp_pb2.Timestamp = proto.Field( 

209 proto.MESSAGE, 

210 number=10, 

211 oneof="value_type", 

212 message=timestamp_pb2.Timestamp, 

213 ) 

214 string_value: str = proto.Field( 

215 proto.STRING, 

216 number=17, 

217 oneof="value_type", 

218 ) 

219 bytes_value: bytes = proto.Field( 

220 proto.BYTES, 

221 number=18, 

222 oneof="value_type", 

223 ) 

224 reference_value: str = proto.Field( 

225 proto.STRING, 

226 number=5, 

227 oneof="value_type", 

228 ) 

229 geo_point_value: latlng_pb2.LatLng = proto.Field( 

230 proto.MESSAGE, 

231 number=8, 

232 oneof="value_type", 

233 message=latlng_pb2.LatLng, 

234 ) 

235 array_value: "ArrayValue" = proto.Field( 

236 proto.MESSAGE, 

237 number=9, 

238 oneof="value_type", 

239 message="ArrayValue", 

240 ) 

241 map_value: "MapValue" = proto.Field( 

242 proto.MESSAGE, 

243 number=6, 

244 oneof="value_type", 

245 message="MapValue", 

246 ) 

247 

248 

249class ArrayValue(proto.Message): 

250 r"""An array value. 

251 

252 Attributes: 

253 values (MutableSequence[google.cloud.firestore_v1.types.Value]): 

254 Values in the array. 

255 """ 

256 

257 values: MutableSequence["Value"] = proto.RepeatedField( 

258 proto.MESSAGE, 

259 number=1, 

260 message="Value", 

261 ) 

262 

263 

264class MapValue(proto.Message): 

265 r"""A map value. 

266 

267 Attributes: 

268 fields (MutableMapping[str, google.cloud.firestore_v1.types.Value]): 

269 The map's fields. 

270 

271 The map keys represent field names. Field names matching the 

272 regular expression ``__.*__`` are reserved. Reserved field 

273 names are forbidden except in certain documented contexts. 

274 The map keys, represented as UTF-8, must not exceed 1,500 

275 bytes and cannot be empty. 

276 """ 

277 

278 fields: MutableMapping[str, "Value"] = proto.MapField( 

279 proto.STRING, 

280 proto.MESSAGE, 

281 number=1, 

282 message="Value", 

283 ) 

284 

285 

286__all__ = tuple(sorted(__protobuf__.manifest))