Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/google/api_core/exceptions.py: 62%

1# Copyright 2014 Google LLC 

2# 

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

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

5# You may obtain a copy of the License at 

6# 

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

8# 

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

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

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

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

13# limitations under the License. 

14 

15"""Exceptions raised by Google API core & clients. 

16 

17This module provides base classes for all errors raised by libraries based 

18on :mod:`google.api_core`, including both HTTP and gRPC clients. 

19""" 

20 

21from __future__ import absolute_import 

22from __future__ import unicode_literals 

23 

24import http.client 

25from typing import Optional, Dict 

26import warnings 

27 

28from google.rpc import error_details_pb2 

29 

30 

31def _warn_could_not_import_grpcio_status(): 

32 warnings.warn( 

33 "Please install grpcio-status to obtain helpful grpc error messages.", 

34 ImportWarning, 

35 ) # pragma: NO COVER 

36 

37 

38try: 

39 import grpc 

40 

41 try: 

42 from grpc_status import rpc_status 

43 except ImportError: # pragma: NO COVER 

44 _warn_could_not_import_grpcio_status() 

45 rpc_status = None 

46except ImportError: # pragma: NO COVER 

47 grpc = None 

48 

49# Lookup tables for mapping exceptions from HTTP and gRPC transports. 

50# Populated by _GoogleAPICallErrorMeta 

51_HTTP_CODE_TO_EXCEPTION: Dict[int, Exception] = {} 

52_GRPC_CODE_TO_EXCEPTION: Dict[int, Exception] = {} 

53 

54# Additional lookup table to map integer status codes to grpc status code 

55# grpc does not currently support initializing enums from ints 

56# i.e., grpc.StatusCode(5) raises an error 

57_INT_TO_GRPC_CODE = {} 

58if grpc is not None: # pragma: no branch 

59 for x in grpc.StatusCode: 

60 _INT_TO_GRPC_CODE[x.value[0]] = x 

61 

62 

63class GoogleAPIError(Exception): 

64 """Base class for all exceptions raised by Google API Clients.""" 

65 

66 pass 

67 

68 

69class DuplicateCredentialArgs(GoogleAPIError): 

70 """Raised when multiple credentials are passed.""" 

71 

72 pass 

73 

74 

75class RetryError(GoogleAPIError): 

76 """Raised when a function has exhausted all of its available retries. 

77 

78 Args: 

79 message (str): The exception message. 

80 cause (Exception): The last exception raised when retrying the 

81 function. 

82 """ 

83 

84 def __init__(self, message, cause): 

85 super(RetryError, self).__init__(message) 

86 self.message = message 

87 self._cause = cause 

88 

89 @property 

90 def cause(self): 

91 """The last exception raised when retrying the function.""" 

92 return self._cause 

93 

94 def __str__(self): 

95 return "{}, last exception: {}".format(self.message, self.cause) 

96 

97 

98class _GoogleAPICallErrorMeta(type): 

99 """Metaclass for registering GoogleAPICallError subclasses.""" 

100 

101 def __new__(mcs, name, bases, class_dict): 

102 cls = type.__new__(mcs, name, bases, class_dict) 

103 if cls.code is not None: 

104 _HTTP_CODE_TO_EXCEPTION.setdefault(cls.code, cls) 

105 if cls.grpc_status_code is not None: 

106 _GRPC_CODE_TO_EXCEPTION.setdefault(cls.grpc_status_code, cls) 

107 return cls 

108 

109 

110class GoogleAPICallError(GoogleAPIError, metaclass=_GoogleAPICallErrorMeta): 

111 """Base class for exceptions raised by calling API methods. 

112 

113 Args: 

114 message (str): The exception message. 

115 errors (Sequence[Any]): An optional list of error details. 

116 details (Sequence[Any]): An optional list of objects defined in google.rpc.error_details. 

117 response (Union[requests.Request, grpc.Call]): The response or 

118 gRPC call metadata. 

119 error_info (Union[error_details_pb2.ErrorInfo, None]): An optional object containing error info 

120 (google.rpc.error_details.ErrorInfo). 

121 """ 

122 

123 code: Optional[int] = None 

124 """Optional[int]: The HTTP status code associated with this error. 

125 

126 This may be ``None`` if the exception does not have a direct mapping 

127 to an HTTP error. 

128 

129 See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html 

130 """ 

131 

132 grpc_status_code: Optional["grpc.StatusCode"] = None 

133 """Optional[grpc.StatusCode]: The gRPC status code associated with this 

134 error. 

135 

136 This may be ``None`` if the exception does not match up to a gRPC error. 

137 """ 

138 

139 def __init__(self, message, errors=(), details=(), response=None, error_info=None): 

140 super(GoogleAPICallError, self).__init__(message) 

141 self.message = message 

142 """str: The exception message.""" 

143 self._errors = errors 

144 self._details = details 

145 self._response = response 

146 self._error_info = error_info 

147 

148 def __str__(self): 

149 error_msg = "{} {}".format(self.code, self.message) 

150 if self.details: 

151 error_msg = "{} {}".format(error_msg, self.details) 

152 # Note: This else condition can be removed once proposal A from 

153 # b/284179390 is implemented. 

154 else: 

155 if self.errors: 

156 errors = [ 

157 f"{error.code}: {error.message}" 

158 for error in self.errors 

159 if hasattr(error, "code") and hasattr(error, "message") 

160 ] 

161 if errors: 

162 error_msg = "{} {}".format(error_msg, "\n".join(errors)) 

163 return error_msg 

164 

165 @property 

166 def reason(self): 

167 """The reason of the error. 

168 

169 Reference: 

170 https://github.com/googleapis/googleapis/blob/master/google/rpc/error_details.proto#L112 

171 

172 Returns: 

173 Union[str, None]: An optional string containing reason of the error. 

174 """ 

175 return self._error_info.reason if self._error_info else None 

176 

177 @property 

178 def domain(self): 

179 """The logical grouping to which the "reason" belongs. 

180 

181 Reference: 

182 https://github.com/googleapis/googleapis/blob/master/google/rpc/error_details.proto#L112 

183 

184 Returns: 

185 Union[str, None]: An optional string containing a logical grouping to which the "reason" belongs. 

186 """ 

187 return self._error_info.domain if self._error_info else None 

188 

189 @property 

190 def metadata(self): 

191 """Additional structured details about this error. 

192 

193 Reference: 

194 https://github.com/googleapis/googleapis/blob/master/google/rpc/error_details.proto#L112 

195 

196 Returns: 

197 Union[Dict[str, str], None]: An optional object containing structured details about the error. 

198 """ 

199 return self._error_info.metadata if self._error_info else None 

200 

201 @property 

202 def errors(self): 

203 """Detailed error information. 

204 

205 Returns: 

206 Sequence[Any]: A list of additional error details. 

207 """ 

208 return list(self._errors) 

209 

210 @property 

211 def details(self): 

212 """Information contained in google.rpc.status.details. 

213 

214 Reference: 

215 https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto 

216 https://github.com/googleapis/googleapis/blob/master/google/rpc/error_details.proto 

217 

218 Returns: 

219 Sequence[Any]: A list of structured objects from error_details.proto 

220 """ 

221 return list(self._details) 

222 

223 @property 

224 def response(self): 

225 """Optional[Union[requests.Request, grpc.Call]]: The response or 

226 gRPC call metadata.""" 

227 return self._response 

228 

229 

230class Redirection(GoogleAPICallError): 

231 """Base class for for all redirection (HTTP 3xx) responses.""" 

232 

233 

234class MovedPermanently(Redirection): 

235 """Exception mapping a ``301 Moved Permanently`` response.""" 

236 

237 code = http.client.MOVED_PERMANENTLY 

238 

239 

240class NotModified(Redirection): 

241 """Exception mapping a ``304 Not Modified`` response.""" 

242 

243 code = http.client.NOT_MODIFIED 

244 

245 

246class TemporaryRedirect(Redirection): 

247 """Exception mapping a ``307 Temporary Redirect`` response.""" 

248 

249 code = http.client.TEMPORARY_REDIRECT 

250 

251 

252class ResumeIncomplete(Redirection): 

253 """Exception mapping a ``308 Resume Incomplete`` response. 

254 

255 .. note:: :attr:`http.client.PERMANENT_REDIRECT` is ``308``, but Google 

256 APIs differ in their use of this status code. 

257 """ 

258 

259 code = 308 

260 

261 

262class ClientError(GoogleAPICallError): 

263 """Base class for all client error (HTTP 4xx) responses.""" 

264 

265 

266class BadRequest(ClientError): 

267 """Exception mapping a ``400 Bad Request`` response.""" 

268 

269 code = http.client.BAD_REQUEST 

270 

271 

272class InvalidArgument(BadRequest): 

273 """Exception mapping a :attr:`grpc.StatusCode.INVALID_ARGUMENT` error.""" 

274 

275 grpc_status_code = grpc.StatusCode.INVALID_ARGUMENT if grpc is not None else None 

276 

277 

278class FailedPrecondition(BadRequest): 

279 """Exception mapping a :attr:`grpc.StatusCode.FAILED_PRECONDITION` 

280 error.""" 

281 

282 grpc_status_code = grpc.StatusCode.FAILED_PRECONDITION if grpc is not None else None 

283 

284 

285class OutOfRange(BadRequest): 

286 """Exception mapping a :attr:`grpc.StatusCode.OUT_OF_RANGE` error.""" 

287 

288 grpc_status_code = grpc.StatusCode.OUT_OF_RANGE if grpc is not None else None 

289 

290 

291class Unauthorized(ClientError): 

292 """Exception mapping a ``401 Unauthorized`` response.""" 

293 

294 code = http.client.UNAUTHORIZED 

295 

296 

297class Unauthenticated(Unauthorized): 

298 """Exception mapping a :attr:`grpc.StatusCode.UNAUTHENTICATED` error.""" 

299 

300 grpc_status_code = grpc.StatusCode.UNAUTHENTICATED if grpc is not None else None 

301 

302 

303class Forbidden(ClientError): 

304 """Exception mapping a ``403 Forbidden`` response.""" 

305 

306 code = http.client.FORBIDDEN 

307 

308 

309class PermissionDenied(Forbidden): 

310 """Exception mapping a :attr:`grpc.StatusCode.PERMISSION_DENIED` error.""" 

311 

312 grpc_status_code = grpc.StatusCode.PERMISSION_DENIED if grpc is not None else None 

313 

314 

315class NotFound(ClientError): 

316 """Exception mapping a ``404 Not Found`` response or a 

317 :attr:`grpc.StatusCode.NOT_FOUND` error.""" 

318 

319 code = http.client.NOT_FOUND 

320 grpc_status_code = grpc.StatusCode.NOT_FOUND if grpc is not None else None 

321 

322 

323class MethodNotAllowed(ClientError): 

324 """Exception mapping a ``405 Method Not Allowed`` response.""" 

325 

326 code = http.client.METHOD_NOT_ALLOWED 

327 

328 

329class Conflict(ClientError): 

330 """Exception mapping a ``409 Conflict`` response.""" 

331 

332 code = http.client.CONFLICT 

333 

334 

335class AlreadyExists(Conflict): 

336 """Exception mapping a :attr:`grpc.StatusCode.ALREADY_EXISTS` error.""" 

337 

338 grpc_status_code = grpc.StatusCode.ALREADY_EXISTS if grpc is not None else None 

339 

340 

341class Aborted(Conflict): 

342 """Exception mapping a :attr:`grpc.StatusCode.ABORTED` error.""" 

343 

344 grpc_status_code = grpc.StatusCode.ABORTED if grpc is not None else None 

345 

346 

347class LengthRequired(ClientError): 

348 """Exception mapping a ``411 Length Required`` response.""" 

349 

350 code = http.client.LENGTH_REQUIRED 

351 

352 

353class PreconditionFailed(ClientError): 

354 """Exception mapping a ``412 Precondition Failed`` response.""" 

355 

356 code = http.client.PRECONDITION_FAILED 

357 

358 

359class RequestRangeNotSatisfiable(ClientError): 

360 """Exception mapping a ``416 Request Range Not Satisfiable`` response.""" 

361 

362 code = http.client.REQUESTED_RANGE_NOT_SATISFIABLE 

363 

364 

365class TooManyRequests(ClientError): 

366 """Exception mapping a ``429 Too Many Requests`` response.""" 

367 

368 code = http.client.TOO_MANY_REQUESTS 

369 

370 

371class ResourceExhausted(TooManyRequests): 

372 """Exception mapping a :attr:`grpc.StatusCode.RESOURCE_EXHAUSTED` error.""" 

373 

374 grpc_status_code = grpc.StatusCode.RESOURCE_EXHAUSTED if grpc is not None else None 

375 

376 

377class Cancelled(ClientError): 

378 """Exception mapping a :attr:`grpc.StatusCode.CANCELLED` error.""" 

379 

380 # This maps to HTTP status code 499. See 

381 # https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto 

382 code = 499 

383 grpc_status_code = grpc.StatusCode.CANCELLED if grpc is not None else None 

384 

385 

386class ServerError(GoogleAPICallError): 

387 """Base for 5xx responses.""" 

388 

389 

390class InternalServerError(ServerError): 

391 """Exception mapping a ``500 Internal Server Error`` response. or a 

392 :attr:`grpc.StatusCode.INTERNAL` error.""" 

393 

394 code = http.client.INTERNAL_SERVER_ERROR 

395 grpc_status_code = grpc.StatusCode.INTERNAL if grpc is not None else None 

396 

397 

398class Unknown(ServerError): 

399 """Exception mapping a :attr:`grpc.StatusCode.UNKNOWN` error.""" 

400 

401 grpc_status_code = grpc.StatusCode.UNKNOWN if grpc is not None else None 

402 

403 

404class DataLoss(ServerError): 

405 """Exception mapping a :attr:`grpc.StatusCode.DATA_LOSS` error.""" 

406 

407 grpc_status_code = grpc.StatusCode.DATA_LOSS if grpc is not None else None 

408 

409 

410class MethodNotImplemented(ServerError): 

411 """Exception mapping a ``501 Not Implemented`` response or a 

412 :attr:`grpc.StatusCode.UNIMPLEMENTED` error.""" 

413 

414 code = http.client.NOT_IMPLEMENTED 

415 grpc_status_code = grpc.StatusCode.UNIMPLEMENTED if grpc is not None else None 

416 

417 

418class BadGateway(ServerError): 

419 """Exception mapping a ``502 Bad Gateway`` response.""" 

420 

421 code = http.client.BAD_GATEWAY 

422 

423 

424class ServiceUnavailable(ServerError): 

425 """Exception mapping a ``503 Service Unavailable`` response or a 

426 :attr:`grpc.StatusCode.UNAVAILABLE` error.""" 

427 

428 code = http.client.SERVICE_UNAVAILABLE 

429 grpc_status_code = grpc.StatusCode.UNAVAILABLE if grpc is not None else None 

430 

431 

432class GatewayTimeout(ServerError): 

433 """Exception mapping a ``504 Gateway Timeout`` response.""" 

434 

435 code = http.client.GATEWAY_TIMEOUT 

436 

437 

438class DeadlineExceeded(GatewayTimeout): 

439 """Exception mapping a :attr:`grpc.StatusCode.DEADLINE_EXCEEDED` error.""" 

440 

441 grpc_status_code = grpc.StatusCode.DEADLINE_EXCEEDED if grpc is not None else None 

442 

443 

444class AsyncRestUnsupportedParameterError(NotImplementedError): 

445 """Raised when an unsupported parameter is configured against async rest transport.""" 

446 

447 pass 

448 

449 

450def exception_class_for_http_status(status_code): 

451 """Return the exception class for a specific HTTP status code. 

452 

453 Args: 

454 status_code (int): The HTTP status code. 

455 

456 Returns: 

457 :func:`type`: the appropriate subclass of :class:`GoogleAPICallError`. 

458 """ 

459 return _HTTP_CODE_TO_EXCEPTION.get(status_code, GoogleAPICallError) 

460 

461 

462def from_http_status(status_code, message, **kwargs): 

463 """Create a :class:`GoogleAPICallError` from an HTTP status code. 

464 

465 Args: 

466 status_code (int): The HTTP status code. 

467 message (str): The exception message. 

468 kwargs: Additional arguments passed to the :class:`GoogleAPICallError` 

469 constructor. 

470 

471 Returns: 

472 GoogleAPICallError: An instance of the appropriate subclass of 

473 :class:`GoogleAPICallError`. 

474 """ 

475 error_class = exception_class_for_http_status(status_code) 

476 error = error_class(message, **kwargs) 

477 

478 if error.code is None: 

479 error.code = status_code 

480 

481 return error 

482 

483 

484def _format_rest_error_message(error, method, url): 

485 method = method.upper() if method else None 

486 message = "{method} {url}: {error}".format( 

487 method=method, 

488 url=url, 

489 error=error, 

490 ) 

491 return message 

492 

493 

494# NOTE: We're moving away from `from_http_status` because it expects an aiohttp response compared 

495# to `format_http_response_error` which expects a more abstract response from google.auth and is 

496# compatible with both sync and async response types. 

497# TODO(https://github.com/googleapis/python-api-core/issues/691): Add type hint for response. 

498def format_http_response_error( 

499 response, method: str, url: str, payload: Optional[Dict] = None 

500): 

501 """Create a :class:`GoogleAPICallError` from a google auth rest response. 

502 

503 Args: 

504 response Union[google.auth.transport.Response, google.auth.aio.transport.Response]: The HTTP response. 

505 method Optional(str): The HTTP request method. 

506 url Optional(str): The HTTP request url. 

507 payload Optional(dict): The HTTP response payload. If not passed in, it is read from response for a response type of google.auth.transport.Response. 

508 

509 Returns: 

510 GoogleAPICallError: An instance of the appropriate subclass of 

511 :class:`GoogleAPICallError`, with the message and errors populated 

512 from the response. 

513 """ 

514 payload = {} if not payload else payload 

515 error_message = payload.get("error", {}).get("message", "unknown error") 

516 errors = payload.get("error", {}).get("errors", ()) 

517 # In JSON, details are already formatted in developer-friendly way. 

518 details = payload.get("error", {}).get("details", ()) 

519 error_info_list = list( 

520 filter( 

521 lambda detail: detail.get("@type", "") 

522 == "type.googleapis.com/google.rpc.ErrorInfo", 

523 details, 

524 ) 

525 ) 

526 error_info = error_info_list[0] if error_info_list else None 

527 message = _format_rest_error_message(error_message, method, url) 

528 

529 exception = from_http_status( 

530 response.status_code, 

531 message, 

532 errors=errors, 

533 details=details, 

534 response=response, 

535 error_info=error_info, 

536 ) 

537 return exception 

538 

539 

540def from_http_response(response): 

541 """Create a :class:`GoogleAPICallError` from a :class:`requests.Response`. 

542 

543 Args: 

544 response (requests.Response): The HTTP response. 

545 

546 Returns: 

547 GoogleAPICallError: An instance of the appropriate subclass of 

548 :class:`GoogleAPICallError`, with the message and errors populated 

549 from the response. 

550 """ 

551 try: 

552 payload = response.json() 

553 except ValueError: 

554 payload = {"error": {"message": response.text or "unknown error"}} 

555 return format_http_response_error( 

556 response, response.request.method, response.request.url, payload 

557 ) 

558 

559 

560def exception_class_for_grpc_status(status_code): 

561 """Return the exception class for a specific :class:`grpc.StatusCode`. 

562 

563 Args: 

564 status_code (grpc.StatusCode): The gRPC status code. 

565 

566 Returns: 

567 :func:`type`: the appropriate subclass of :class:`GoogleAPICallError`. 

568 """ 

569 return _GRPC_CODE_TO_EXCEPTION.get(status_code, GoogleAPICallError) 

570 

571 

572def from_grpc_status(status_code, message, **kwargs): 

573 """Create a :class:`GoogleAPICallError` from a :class:`grpc.StatusCode`. 

574 

575 Args: 

576 status_code (Union[grpc.StatusCode, int]): The gRPC status code. 

577 message (str): The exception message. 

578 kwargs: Additional arguments passed to the :class:`GoogleAPICallError` 

579 constructor. 

580 

581 Returns: 

582 GoogleAPICallError: An instance of the appropriate subclass of 

583 :class:`GoogleAPICallError`. 

584 """ 

585 

586 if isinstance(status_code, int): 

587 status_code = _INT_TO_GRPC_CODE.get(status_code, status_code) 

588 

589 error_class = exception_class_for_grpc_status(status_code) 

590 error = error_class(message, **kwargs) 

591 

592 if error.grpc_status_code is None: 

593 error.grpc_status_code = status_code 

594 

595 return error 

596 

597 

598def _is_informative_grpc_error(rpc_exc): 

599 return hasattr(rpc_exc, "code") and hasattr(rpc_exc, "details") 

600 

601 

602def _parse_grpc_error_details(rpc_exc): 

603 if not rpc_status: # pragma: NO COVER 

604 _warn_could_not_import_grpcio_status() 

605 return [], None 

606 try: 

607 status = rpc_status.from_call(rpc_exc) 

608 except NotImplementedError: # workaround 

609 return [], None 

610 

611 if not status: 

612 return [], None 

613 

614 possible_errors = [ 

615 error_details_pb2.BadRequest, 

616 error_details_pb2.PreconditionFailure, 

617 error_details_pb2.QuotaFailure, 

618 error_details_pb2.ErrorInfo, 

619 error_details_pb2.RetryInfo, 

620 error_details_pb2.ResourceInfo, 

621 error_details_pb2.RequestInfo, 

622 error_details_pb2.DebugInfo, 

623 error_details_pb2.Help, 

624 error_details_pb2.LocalizedMessage, 

625 ] 

626 error_info = None 

627 error_details = [] 

628 for detail in status.details: 

629 matched_detail_cls = list( 

630 filter(lambda x: detail.Is(x.DESCRIPTOR), possible_errors) 

631 ) 

632 # If nothing matched, use detail directly. 

633 if len(matched_detail_cls) == 0: 

634 info = detail 

635 else: 

636 info = matched_detail_cls[0]() 

637 detail.Unpack(info) 

638 error_details.append(info) 

639 if isinstance(info, error_details_pb2.ErrorInfo): 

640 error_info = info 

641 return error_details, error_info 

642 

643 

644def from_grpc_error(rpc_exc): 

645 """Create a :class:`GoogleAPICallError` from a :class:`grpc.RpcError`. 

646 

647 Args: 

648 rpc_exc (grpc.RpcError): The gRPC error. 

649 

650 Returns: 

651 GoogleAPICallError: An instance of the appropriate subclass of 

652 :class:`GoogleAPICallError`. 

653 """ 

654 # NOTE(lidiz) All gRPC error shares the parent class grpc.RpcError. 

655 # However, check for grpc.RpcError breaks backward compatibility. 

656 if ( 

657 grpc is not None and isinstance(rpc_exc, grpc.Call) 

658 ) or _is_informative_grpc_error(rpc_exc): 

659 details, err_info = _parse_grpc_error_details(rpc_exc) 

660 return from_grpc_status( 

661 rpc_exc.code(), 

662 rpc_exc.details(), 

663 errors=(rpc_exc,), 

664 details=details, 

665 response=rpc_exc, 

666 error_info=err_info, 

667 ) 

668 else: 

669 return GoogleAPICallError(str(rpc_exc), errors=(rpc_exc,), response=rpc_exc)