"""Describe method for collections 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__.collections import CollectionInfoProtocol
    from pinecone.models.collections import CollectionModel

logger = get_logger(__name__)


def describe(self: Any, name: str) -> CollectionInfoProtocol:
    """Get collection details.

    Args:
        name: Collection name.

    Returns:
        CollectionInfoProtocol with metadata including name, size, status,
        dimension, vector_count, and environment.

    Raises:
        ValueError: If name is empty.
        NotFoundError: If collection not found.
        APIError: If operation fails.

    Example:
        >>> info = pc.collections.describe("my-backup")
        >>> print(f"Status: {info.status}")
        >>> print(f"Vectors: {info.vector_count}")
    """
    # Validate inputs
    require_non_empty("name", name)

    logger.info(
        "Describing collection",
        collection_name=name,
    )

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

        # Transform response
        data = orjson.loads(response.content)
        result: CollectionModel = self._adapter.to_collection_model(data)

        logger.debug(
            "Successfully described collection", collection_name=name, status=result.status
        )

        return result  # noqa: TRY300

    except Exception:
        logger.exception("Failed to describe collection", collection_name=name)
        raise
