Source code for pyathena.filesystem.s3_errors

# 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