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

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, unicode_literals 

22 

23import http.client 

24import warnings 

25from typing import Dict, Optional 

26 

27from google.rpc import error_details_pb2 

28 

29 

30def _warn_could_not_import_grpcio_status(): 

31 warnings.warn( 

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

33 ImportWarning, 

34 ) # pragma: NO COVER 

35 

36 

37try: 

38 import grpc 

39 

40 try: 

41 from grpc_status import rpc_status 

42 except ImportError: # pragma: NO COVER 

43 _warn_could_not_import_grpcio_status() 

44 rpc_status = None 

45except ImportError: # pragma: NO COVER 

46 grpc = None 

47 

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

49# Populated by _GoogleAPICallErrorMeta 

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

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

52 

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

54# grpc does not currently support initializing enums from ints 

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

56_INT_TO_GRPC_CODE = {} 

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

58 for x in grpc.StatusCode: 

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

60 

61 

62class GoogleAPIError(Exception): 

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

64 

65 pass 

66 

67 

68class DuplicateCredentialArgs(GoogleAPIError): 

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

70 

71 pass 

72 

73 

74class RetryError(GoogleAPIError): 

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

76 

77 Args: 

78 message (str): The exception message. 

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

80 function. 

81 """ 

82 

83 def __init__(self, message, cause): 

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

85 self.message = message 

86 self._cause = cause 

87 

88 @property 

89 def cause(self): 

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

91 return self._cause 

92 

93 def __str__(self): 

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

95 

96 

97class _GoogleAPICallErrorMeta(type): 

98 """Metaclass for registering GoogleAPICallError subclasses.""" 

99 

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

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

102 if cls.code is not None: 

103 _HTTP_CODE_TO_EXCEPTION.setdefault(cls.code, cls) 

104 if cls.grpc_status_code is not None: 

105 _GRPC_CODE_TO_EXCEPTION.setdefault(cls.grpc_status_code, cls) 

106 return cls 

107 

108 

109class GoogleAPICallError(GoogleAPIError, metaclass=_GoogleAPICallErrorMeta): 

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

111 

112 Args: 

113 message (str): The exception message. 

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

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

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

117 gRPC call metadata. 

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

119 (google.rpc.error_details.ErrorInfo). 

120 """ 

121 

122 code: Optional[int] = None 

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

124 

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

126 to an HTTP error. 

127 

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

129 """ 

130 

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

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

133 error. 

134 

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

136 """ 

137 

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

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

140 self.message = message 

141 """str: The exception message.""" 

142 self._errors = errors 

143 self._details = details 

144 self._response = response 

145 self._error_info = error_info 

146 

147 def __str__(self): 

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

149 if self.details: 

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

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

152 # b/284179390 is implemented. 

153 else: 

154 if self.errors: 

155 errors = [ 

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

157 for error in self.errors 

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

159 ] 

160 if errors: 

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

162 return error_msg 

163 

164 @property 

165 def reason(self): 

166 """The reason of the error. 

167 

168 Reference: 

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

170 

171 Returns: 

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

173 """ 

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

175 

176 @property 

177 def domain(self): 

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

179 

180 Reference: 

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

182 

183 Returns: 

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

185 """ 

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

187 

188 @property 

189 def metadata(self): 

190 """Additional structured details about this error. 

191 

192 Reference: 

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

194 

195 Returns: 

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

197 """ 

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

199 

200 @property 

201 def errors(self): 

202 """Detailed error information. 

203 

204 Returns: 

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

206 """ 

207 return list(self._errors) 

208 

209 @property 

210 def details(self): 

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

212 

213 Reference: 

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

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

216 

217 Returns: 

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

219 """ 

220 return list(self._details) 

221 

222 @property 

223 def response(self): 

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

225 gRPC call metadata.""" 

226 return self._response 

227 

228 

229class Redirection(GoogleAPICallError): 

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

231 

232 

233class MovedPermanently(Redirection): 

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

235 

236 code = http.client.MOVED_PERMANENTLY 

237 

238 

239class NotModified(Redirection): 

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

241 

242 code = http.client.NOT_MODIFIED 

243 

244 

245class TemporaryRedirect(Redirection): 

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

247 

248 code = http.client.TEMPORARY_REDIRECT 

249 

250 

251class ResumeIncomplete(Redirection): 

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

253 

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

255 APIs differ in their use of this status code. 

256 """ 

257 

258 code = 308 

259 

260 

261class ClientError(GoogleAPICallError): 

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

263 

264 

265class BadRequest(ClientError): 

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

267 

268 code = http.client.BAD_REQUEST 

269 

270 

271class InvalidArgument(BadRequest): 

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

273 

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

275 

276 

277class FailedPrecondition(BadRequest): 

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

279 error.""" 

280 

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

282 

283 

284class OutOfRange(BadRequest): 

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

286 

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

288 

289 

290class Unauthorized(ClientError): 

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

292 

293 code = http.client.UNAUTHORIZED 

294 

295 

296class Unauthenticated(Unauthorized): 

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

298 

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

300 

301 

302class Forbidden(ClientError): 

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

304 

305 code = http.client.FORBIDDEN 

306 

307 

308class PermissionDenied(Forbidden): 

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

310 

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

312 

313 

314class NotFound(ClientError): 

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

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

317 

318 code = http.client.NOT_FOUND 

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

320 

321 

322class MethodNotAllowed(ClientError): 

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

324 

325 code = http.client.METHOD_NOT_ALLOWED 

326 

327 

328class Conflict(ClientError): 

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

330 

331 code = http.client.CONFLICT 

332 

333 

334class AlreadyExists(Conflict): 

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

336 

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

338 

339 

340class Aborted(Conflict): 

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

342 

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

344 

345 

346class LengthRequired(ClientError): 

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

348 

349 code = http.client.LENGTH_REQUIRED 

350 

351 

352class PreconditionFailed(ClientError): 

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

354 

355 code = http.client.PRECONDITION_FAILED 

356 

357 

358class RequestRangeNotSatisfiable(ClientError): 

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

360 

361 code = http.client.REQUESTED_RANGE_NOT_SATISFIABLE 

362 

363 

364class TooManyRequests(ClientError): 

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

366 

367 code = http.client.TOO_MANY_REQUESTS 

368 

369 

370class ResourceExhausted(TooManyRequests): 

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

372 

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

374 

375 

376class Cancelled(ClientError): 

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

378 

379 # This maps to HTTP status code 499. See 

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

381 code = 499 

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

383 

384 

385class ServerError(GoogleAPICallError): 

386 """Base for 5xx responses.""" 

387 

388 

389class InternalServerError(ServerError): 

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

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

392 

393 code = http.client.INTERNAL_SERVER_ERROR 

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

395 

396 

397class Unknown(ServerError): 

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

399 

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

401 

402 

403class DataLoss(ServerError): 

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

405 

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

407 

408 

409class MethodNotImplemented(ServerError): 

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

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

412 

413 code = http.client.NOT_IMPLEMENTED 

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

415 

416 

417class BadGateway(ServerError): 

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

419 

420 code = http.client.BAD_GATEWAY 

421 

422 

423class ServiceUnavailable(ServerError): 

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

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

426 

427 code = http.client.SERVICE_UNAVAILABLE 

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

429 

430 

431class GatewayTimeout(ServerError): 

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

433 

434 code = http.client.GATEWAY_TIMEOUT 

435 

436 

437class DeadlineExceeded(GatewayTimeout): 

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

439 

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

441 

442 

443class AsyncRestUnsupportedParameterError(NotImplementedError): 

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

445 

446 pass 

447 

448 

449def exception_class_for_http_status(status_code): 

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

451 

452 Args: 

453 status_code (int): The HTTP status code. 

454 

455 Returns: 

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

457 """ 

458 return _HTTP_CODE_TO_EXCEPTION.get(status_code, GoogleAPICallError) 

459 

460 

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

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

463 

464 Args: 

465 status_code (int): The HTTP status code. 

466 message (str): The exception message. 

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

468 constructor. 

469 

470 Returns: 

471 GoogleAPICallError: An instance of the appropriate subclass of 

472 :class:`GoogleAPICallError`. 

473 """ 

474 error_class = exception_class_for_http_status(status_code) 

475 error = error_class(message, **kwargs) 

476 

477 if error.code is None: 

478 error.code = status_code 

479 

480 return error 

481 

482 

483def _format_rest_error_message(error, method, url): 

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

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

486 method=method, 

487 url=url, 

488 error=error, 

489 ) 

490 return message 

491 

492 

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

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

495# compatible with both sync and async response types. 

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

497def format_http_response_error( 

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

499): 

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

501 

502 Args: 

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

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

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

506 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. 

507 

508 Returns: 

509 GoogleAPICallError: An instance of the appropriate subclass of 

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

511 from the response. 

512 """ 

513 payload = {} if not payload else payload 

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

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

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

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

518 error_info_list = list( 

519 filter( 

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

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

522 details, 

523 ) 

524 ) 

525 error_info = error_info_list[0] if error_info_list else None 

526 message = _format_rest_error_message(error_message, method, url) 

527 

528 exception = from_http_status( 

529 response.status_code, 

530 message, 

531 errors=errors, 

532 details=details, 

533 response=response, 

534 error_info=error_info, 

535 ) 

536 return exception 

537 

538 

539def from_http_response(response): 

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

541 

542 Args: 

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

544 

545 Returns: 

546 GoogleAPICallError: An instance of the appropriate subclass of 

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

548 from the response. 

549 """ 

550 try: 

551 payload = response.json() 

552 except ValueError: 

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

554 return format_http_response_error( 

555 response, response.request.method, response.request.url, payload 

556 ) 

557 

558 

559def exception_class_for_grpc_status(status_code): 

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

561 

562 Args: 

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

564 

565 Returns: 

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

567 """ 

568 return _GRPC_CODE_TO_EXCEPTION.get(status_code, GoogleAPICallError) 

569 

570 

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

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

573 

574 Args: 

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

576 message (str): The exception message. 

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

578 constructor. 

579 

580 Returns: 

581 GoogleAPICallError: An instance of the appropriate subclass of 

582 :class:`GoogleAPICallError`. 

583 """ 

584 

585 if isinstance(status_code, int): 

586 status_code = _INT_TO_GRPC_CODE.get(status_code, status_code) 

587 

588 error_class = exception_class_for_grpc_status(status_code) 

589 error = error_class(message, **kwargs) 

590 

591 if error.grpc_status_code is None: 

592 error.grpc_status_code = status_code 

593 

594 return error 

595 

596 

597def _is_informative_grpc_error(rpc_exc): 

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

599 

600 

601def _parse_grpc_error_details(rpc_exc): 

602 if not rpc_status: # pragma: NO COVER 

603 _warn_could_not_import_grpcio_status() 

604 return [], None 

605 try: 

606 status = rpc_status.from_call(rpc_exc) 

607 except NotImplementedError: # workaround 

608 return [], None 

609 

610 if not status: 

611 return [], None 

612 

613 possible_errors = [ 

614 error_details_pb2.BadRequest, 

615 error_details_pb2.PreconditionFailure, 

616 error_details_pb2.QuotaFailure, 

617 error_details_pb2.ErrorInfo, 

618 error_details_pb2.RetryInfo, 

619 error_details_pb2.ResourceInfo, 

620 error_details_pb2.RequestInfo, 

621 error_details_pb2.DebugInfo, 

622 error_details_pb2.Help, 

623 error_details_pb2.LocalizedMessage, 

624 ] 

625 error_info = None 

626 error_details = [] 

627 for detail in status.details: 

628 matched_detail_cls = list( 

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

630 ) 

631 # If nothing matched, use detail directly. 

632 if len(matched_detail_cls) == 0: 

633 info = detail 

634 else: 

635 info = matched_detail_cls[0]() 

636 detail.Unpack(info) 

637 error_details.append(info) 

638 if isinstance(info, error_details_pb2.ErrorInfo): 

639 error_info = info 

640 return error_details, error_info 

641 

642 

643def from_grpc_error(rpc_exc): 

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

645 

646 Args: 

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

648 

649 Returns: 

650 GoogleAPICallError: An instance of the appropriate subclass of 

651 :class:`GoogleAPICallError`. 

652 """ 

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

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

655 if ( 

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

657 ) or _is_informative_grpc_error(rpc_exc): 

658 details, err_info = _parse_grpc_error_details(rpc_exc) 

659 message = rpc_exc.details() 

660 if ( 

661 grpc is not None 

662 and rpc_exc.code() == grpc.StatusCode.UNIMPLEMENTED 

663 and "Received http2 header with status: 404" in message 

664 ): 

665 message = ( 

666 f"{message}. This usually indicates that the 'api_endpoint' " 

667 "configuration in ClientOptions is incorrect, contains a typo, " 

668 "or is an invalid regional endpoint for this service." 

669 ) 

670 return from_grpc_status( 

671 rpc_exc.code(), 

672 message, 

673 errors=(rpc_exc,), 

674 details=details, 

675 response=rpc_exc, 

676 error_info=err_info, 

677 ) 

678 else: 

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