#
# # Copyright © 2026 Peak AI Limited. or its affiliates. All Rights Reserved.
# #
# # Licensed under the Apache License, Version 2.0 (the "License"). You
# # may not use this file except in compliance with the License. A copy of
# # the License is located at:
# #
# # https://github.com/PeakBI/peak-sdk/blob/main/LICENSE
# #
# # or in the "license" file accompanying this file. This file is
# # distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
# # ANY KIND, either express or implied. See the License for the specific
# # language governing permissions and limitations under the License.
# #
# # This file is part of the peak-sdk.
# # see (https://github.com/PeakBI/peak-sdk)
# #
# # You should have received a copy of the APACHE LICENSE, VERSION 2.0
# # along with this program. If not, see <https://apache.org/licenses/LICENSE-2.0>
#
"""S3 object existence check operations."""

from __future__ import annotations

from botocore.client import BaseClient  # type: ignore[import-not-found]
from botocore.exceptions import ClientError  # type: ignore[import-not-found]


def object_exists(s3_client: BaseClient, bucket_name: str, key: str) -> bool:
    """Check if an object exists in the S3 bucket `bucket_name`.

    Sends a `head_object` request to determine if the object exists at the
    given key.

    Parameters
    ----------
    s3_client:
        s3 client instance.
    bucket_name: str
        The s3 bucket name.
    key: str
        The s3 key to check.

    Returns:
    -------
    bool
        True if the object exists, False if it does not.

    Raises:
    ------
    botocore.exceptions.ClientError
        If an error occurs other than a 404 (Not Found).
    """
    try:
        s3_client.head_object(Bucket=bucket_name, Key=key)
    except ClientError as client_error:
        if client_error.response["Error"]["Code"] == "404":
            return False
        raise
    return True
