"""Describe method for async_backups namespace."""

from __future__ import annotations

from typing import TYPE_CHECKING, Any

import orjson

from pinecone._internal.logging import get_logger
from pinecone._internal.validation import require_non_empty


if TYPE_CHECKING:
    from pinecone.__interface__.backups import BackupInfoProtocol

logger = get_logger(__name__)


async def describe(self: Any, backup_id: str) -> BackupInfoProtocol:
    """Get backup details asynchronously.

    Args:
        backup_id: Unique identifier of the backup.

    Returns:
        BackupInfoProtocol with complete backup metadata including status,
        size, record count, and more.

    Raises:
        ValueError: If backup_id is empty.
        NotFoundError: If backup not found.
        APIError: If operation fails.

    Example:
        >>> info = await pc.backups.describe("8c85e612-ed1c-4f97-9f8c-8194e07bcf71")
        >>> print(f"Status: {info.status}")
        >>> print(f"Size: {info.size_bytes} bytes")
        >>> print(f"Records: {info.record_count}")
    """
    # Validate inputs
    require_non_empty("backup_id", backup_id)

    logger.info("Describing backup", backup_id=backup_id)

    try:
        # Make HTTP request
        response = await self._http.get(
            f"{self._base_url}/backups/{backup_id}",
            headers=self._headers,
        )

        # Transform response
        data = orjson.loads(response.content)
        result: BackupInfoProtocol = self._adapter.to_backup_model(data)

        logger.debug(
            "Successfully described backup",
            backup_id=backup_id,
            status=result.status,
            size_bytes=result.size_bytes,
        )

        return result  # noqa: TRY300

    except Exception:
        logger.exception("Failed to describe backup", backup_id=backup_id)
        raise
