"""S3 helpers using IRSA (IAM Roles for Service Accounts).

In EKS, the singleuser pod's service account is annotated with an IAM role
that grants access to the ``andlake-app`` bucket.  ``boto3`` picks up
credentials automatically via the IRSA token file — no explicit keys needed.

Usage::

    from andlake import get_s3_client

    s3 = get_s3_client()
    response = s3.list_objects_v2(Bucket="andlake-app", Prefix="trino/warehouse/")
"""

from __future__ import annotations

from typing import TYPE_CHECKING

from andlake.config import get_config

if TYPE_CHECKING:
    from mypy_boto3_s3 import S3Client, S3ServiceResource


def get_s3_client() -> S3Client:
    """Return a ``boto3`` S3 client using IRSA credentials.

    Returns
    -------
    boto3.client("s3")
    """
    import boto3

    # boto3 automatically discovers IRSA credentials from the projected
    # service account token in EKS.  No explicit credentials required.
    return boto3.client("s3")


def get_s3_resource() -> S3ServiceResource:
    """Return a ``boto3`` S3 resource using IRSA credentials.

    The resource interface is convenient for object-oriented S3 access::

        s3 = get_s3_resource()
        bucket = s3.Bucket("andlake-app")
        for obj in bucket.objects.filter(Prefix="trino/warehouse/"):
            print(obj.key)

    Returns
    -------
    boto3.resource("s3")
    """
    import boto3

    return boto3.resource("s3")


def get_default_bucket() -> str:
    """Return the default S3 bucket name from config.

    Returns
    -------
    str
        The bucket name (e.g. ``"andlake-app"``).
    """
    return get_config().s3_bucket
