# Copyright 2026 The PyAthena authors
#
# Licensed under the MIT License.
# See LICENSE or https://opensource.org/licenses/MIT.
#
# SPDX-License-Identifier: MIT
"""Translation of S3 error responses into standard Python exceptions.
Maps botocore ``ClientError`` responses to the matching ``OSError`` subclasses
so that filesystem operations raise natural Python exceptions
(e.g. ``403`` -> ``PermissionError``, ``404`` -> ``FileNotFoundError``).
The error codes are taken from the official list of Amazon S3 error codes:
https://docs.aws.amazon.com/AmazonS3/latest/API/API_Error.html
(see also https://docs.aws.amazon.com/AmazonS3/latest/API/ErrorResponses.html).
The mapping to Python exceptions is PyAthena's own.
"""
from __future__ import annotations
import errno
from typing import ClassVar
import botocore.exceptions
[docs]
class S3ClientError:
"""Represents an S3 error response with its translation to an OSError.
Wraps a botocore ``ClientError`` and exposes the error response fields
as properties, along with :attr:`os_error`, the equivalent standard
Python exception. The error is mapped by its S3 error code first, then
by its HTTP status code; if neither is recognized, a generic ``OSError``
with the original error message is used. A ``PreconditionFailed`` error
of an ``If-None-Match`` condition, from a write that must not replace an
existing object, is mapped to ``FileExistsError``. A ``405`` error with
the ``x-amz-delete-marker: true`` header, from a request for a version
that is a delete marker, is mapped to ``FileNotFoundError``.
Example:
>>> try:
... client.head_object(Bucket="bucket", Key="key")
... except botocore.exceptions.ClientError as e:
... raise S3ClientError(e).os_error from e
"""
# S3 error codes (https://docs.aws.amazon.com/AmazonS3/latest/API/API_Error.html)
# that map to a specific OSError subclass.
# The "403" / "404" entries are not S3 error codes: HEAD requests
# (HeadObject/HeadBucket) have no response body, so botocore reports the
# HTTP status code as the error code instead.
# https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html
_ERROR_CODE_TO_EXCEPTION: ClassVar[dict[str, type[OSError]]] = {
"AccessDenied": PermissionError,
"AccountProblem": PermissionError,
"AllAccessDisabled": PermissionError,
"BucketAlreadyExists": FileExistsError,
"BucketAlreadyOwnedByYou": FileExistsError,
"ExpiredToken": PermissionError,
"InvalidAccessKeyId": PermissionError,
"InvalidObjectState": PermissionError,
"InvalidPayer": PermissionError,
"InvalidSecurity": PermissionError,
"NoSuchBucket": FileNotFoundError,
"NoSuchBucketPolicy": FileNotFoundError,
"NoSuchKey": FileNotFoundError,
"NoSuchLifecycleConfiguration": FileNotFoundError,
"NoSuchUpload": FileNotFoundError,
"NoSuchVersion": FileNotFoundError,
"NotSignedUp": PermissionError,
"RequestTimeout": TimeoutError,
"RequestTimeTooSkewed": PermissionError,
"SignatureDoesNotMatch": PermissionError,
"403": PermissionError,
"404": FileNotFoundError,
}
# S3 error codes (https://docs.aws.amazon.com/AmazonS3/latest/API/API_Error.html)
# that map to an OSError with a specific errno.
_ERROR_CODE_TO_ERRNO: ClassVar[dict[str, int]] = {
"BucketNotEmpty": errno.ENOTEMPTY,
"InternalError": errno.EIO,
"OperationAborted": errno.EBUSY,
"RestoreAlreadyInProgress": errno.EBUSY,
"ServiceUnavailable": errno.EBUSY,
"SlowDown": errno.EBUSY,
}
# Fallbacks by HTTP status code for error codes not listed above.
_HTTP_STATUS_CODE_TO_ERRNO: ClassVar[dict[int, int]] = {
400: errno.EINVAL,
405: errno.EPERM,
409: errno.EBUSY,
412: errno.EINVAL,
416: errno.EINVAL,
500: errno.EIO,
501: errno.ENOSYS,
503: errno.EBUSY,
}
[docs]
def __init__(self, error: botocore.exceptions.ClientError) -> None:
"""Initialize the error from a botocore ``ClientError``.
Args:
error: The ``ClientError`` raised by the S3 client.
"""
error_info = error.response.get("Error", {})
self._code: str = str(error_info.get("Code", ""))
self._message: str = str(error_info.get("Message", error))
self._condition: str = str(error_info.get("Condition", ""))
response_metadata = error.response.get("ResponseMetadata", {})
status_code = response_metadata.get("HTTPStatusCode")
self._http_status_code: int | None = int(status_code) if status_code is not None else None
headers = response_metadata.get("HTTPHeaders", {})
self._delete_marker: bool = headers.get("x-amz-delete-marker") == "true"
self._os_error: OSError = self._translate()
def _translate(self) -> OSError:
if self._code == "PreconditionFailed" and self._condition == "If-None-Match":
# A conditional write (IfNoneMatch="*") found an existing object.
return FileExistsError(self._message)
if self._http_status_code == 405 and self._delete_marker:
# HeadObject/GetObject of a version that is a delete marker.
# https://docs.aws.amazon.com/AmazonS3/latest/userguide/DeleteMarker.html
return FileNotFoundError(self._message)
exception = self._ERROR_CODE_TO_EXCEPTION.get(self._code)
if exception:
return exception(self._message)
errno_ = self._ERROR_CODE_TO_ERRNO.get(self._code)
if errno_ is None:
if self._http_status_code is not None:
errno_ = self._HTTP_STATUS_CODE_TO_ERRNO.get(self._http_status_code, errno.EIO)
else:
errno_ = errno.EIO
return OSError(errno_, self._message)
[docs]
@classmethod
def code_of(cls, error: BaseException) -> str | None:
"""Return the S3 error code of an error raised from a ``ClientError``.
Args:
error: An error, such as the ``OSError`` of a request.
Returns:
The code of the ``ClientError`` that the error was raised from,
or None if it was not raised from one.
"""
cause = error.__cause__
if isinstance(cause, botocore.exceptions.ClientError):
return cls(cause).code
return None
@property
def code(self) -> str:
"""The S3 error code that uniquely identifies the error condition."""
return self._code
@property
def message(self) -> str:
"""The error message returned by the server."""
return self._message
@property
def http_status_code(self) -> int | None:
"""The HTTP status code of the error response."""
return self._http_status_code
@property
def os_error(self) -> OSError:
"""The standard Python exception equivalent to this error response.
Resolved once at construction time. The exception is instantiated
and ready to be raised; raise it with ``raise ... from error`` to
preserve the original exception.
Note:
``OSError`` specializes itself into a subclass for some errno
values (e.g., ``EPERM`` -> ``PermissionError``), so the returned
exception may be a subclass of ``OSError`` even for the
errno-based mappings.
"""
return self._os_error