#
# # 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 model."""

from __future__ import annotations

import datetime as dt

from pydantic import BaseModel, ConfigDict, Field  # type: ignore[import-not-found]


class S3Object(BaseModel):  # type: ignore[misc]
    """S3 object class.

    When working with boto3, s3 client methods tend to return dictionaries of
    fields rather than classes. This class provides a structured means of
    parsing the dictionaries returned by methods such as `list_objects_v2`,
    which means your linter knows what attributes to expect and we can have
    "snake_case" variable names, too.

    Note that this is not an exhaustive list of possible s3 object fields,
    just the most useful ones.

    Fields
    ------
    key: str
        The location of the object, given the bucket.
    last_modified: dt.datetime
        The time the object was modified last.
    etag: str
        Unique identifier
    size_bytes: int
        The object's size, in bytes.
    storage_class: str
        The object's storage class.
    """

    model_config = ConfigDict(extra="ignore")

    key: str = Field(frozen=True, alias="Key")
    last_modified: dt.datetime = Field(frozen=True, alias="LastModified")
    etag: str = Field(frozen=True, alias="ETag")
    size_bytes: int = Field(frozen=True, alias="Size")
    storage_class: str = Field(frozen=True, alias="StorageClass")
