from __future__ import annotations

from io import BytesIO

import pandas as pd

from infrastructure.s3.s3_client import S3Client


class GzipCsvS3Client(S3Client):
    """Reads a gzipped-CSV S3 object into a pandas DataFrame.

    The S3-facing half of the historic-EPC read: an :class:`S3Client` (injected
    boto client + bucket) plus the gzip/CSV decode, so a Repo can depend on this
    instead of the ``utils.s3`` free functions. ``low_memory=False`` so the wide,
    mixed-type historic-EPC columns infer a dtype from the whole column rather
    than per-chunk (which would otherwise split one column across object/float).
    """

    def read_csv_gz(self, key: str) -> pd.DataFrame:
        raw = self.get_object(key)
        # pandas-stubs' read_csv overloads carry bare generics of their own, so
        # strict mode flags the member access; the call and return are typed.
        return pd.read_csv(  # pyright: ignore[reportUnknownMemberType]
            BytesIO(raw), compression="gzip", low_memory=False
        )