"""Describe namespace method for AsyncNamespaces."""

from __future__ import annotations

from typing import Any

import msgspec

from pinecone._internal.validation import require_non_empty
from pinecone.models.namespaces.namespace import NamespaceDescription


_DECODER = msgspec.json.Decoder(NamespaceDescription)


async def describe(self: Any, *, name: str) -> NamespaceDescription:
    """Describe a specific namespace in the index.

    Args:
        name (str): The name of the namespace to describe.

    Returns:
        NamespaceDescription with the namespace details.

    Raises:
        ValueError: If required parameters are empty.
        PineconeApiException: If the API request fails.

    Examples:
        >>> ns = await index.namespaces.describe(name="my-namespace")
        >>> print(f"{ns.name}: {ns.record_count} records")
    """
    require_non_empty("name", name)
    data = await self._make_data_plane_request("GET", f"/namespaces/{name}")
    return _DECODER.decode(data)
